merge: render plan, pipeline, managed encoders and self-test

# Conflicts:
#	src/Titano.Tools/Program.cs
This commit is contained in:
Claude committed 2026-10-02 11:36:35 +00:00
commit 5774592c44
38 files changed
+6649

No files matched your search

+227
View File
@@ -0,0 +1,227 @@
using System.Globalization;
using Titano.Core.Video;
using Titano.Core.Video.Managed;
namespace Titano.Core.Export;
/// <summary>Where a render runs: clients have platform encoders, the server only managed ones (BRIEF §4.2, §14.7).</summary>
public enum EncoderHost
{
Client,
Server,
}
public enum EncoderSelectionStatus
{
/// <summary>An encoder accepts the (possibly adjusted) settings.</summary>
Ready,
/// <summary>The codec needs a platform encoder: delegate the job to a render node (server).</summary>
NeedsRenderNode,
/// <summary>No encoder on this machine can produce the codec.</summary>
Unavailable,
}
/// <summary>A localisable explanation of a selection decision; arguments are invariant-culture strings.</summary>
public sealed record EncoderNotice(string Key, IReadOnlyList<string> Args)
{
public EncoderNotice(string key, params string[] args) : this(key, (IReadOnlyList<string>)args)
{
}
}
/// <summary>Result of <see cref="EncoderSelector.Select"/>.</summary>
public sealed record EncoderSelection
{
public required EncoderSelectionStatus Status { get; init; }
/// <summary>The settings to open the encoder with (codec, size, bit depth or bit rate may differ from the request).</summary>
public required EncodeSettings Settings { get; init; }
public IVideoEncoderProvider? Provider { get; init; }
/// <summary>The capability expected to serve the encode (the provider makes the final choice).</summary>
public EncoderCapability? Capability { get; init; }
/// <summary>Lowest codec level the final settings fit (video codecs only).</summary>
public CodecLevel? Level { get; init; }
public IReadOnlyList<EncoderNotice> Notices { get; init; } = [];
public bool IsReady => Status == EncoderSelectionStatus.Ready;
/// <summary>Opens the session; only valid when <see cref="IsReady"/>.</summary>
public IVideoEncoderSession Open() =>
Provider is not null && IsReady ? Provider.Open(Settings) : throw new InvalidOperationException($"No encoder is ready ({Status})");
}
/// <summary>Notice keys produced by <see cref="EncoderSelector"/>.</summary>
public static class EncoderNotices
{
public const string NeedsRenderNode = "Export.Encoder.NeedsRenderNode";
public const string NoEncoder = "Export.Encoder.NoEncoder";
public const string FallbackToH264 = "Export.Encoder.FallbackToH264";
public const string SoftwareOnly = "Export.Encoder.SoftwareOnly";
public const string TenBitUnavailable = "Export.Encoder.TenBitUnavailable";
public const string BitDepthAdjusted = "Export.Encoder.BitDepthAdjusted";
public const string ResolutionCappedByLevel = "Export.Encoder.ResolutionCappedByLevel";
public const string ResolutionCappedByEncoder = "Export.Encoder.ResolutionCappedByEncoder";
public const string BitRateCapped = "Export.Encoder.BitRateCapped";
}
/// <summary>
/// Picks the encoder for an export (BRIEF §11.3). Providers are given in priority order (client: Media Foundation, then
/// managed; server: managed only).
/// <list type="bullet">
/// <item>Managed codecs go to the first provider that accepts them; an unsupported bit depth becomes the shallowest
/// supported depth that keeps all its precision (or the deepest available).</item>
/// <item>H.264/HEVC/AV1 on the server need a render node. On a client the capability is chosen by named encoder, then
/// 10-bit support when asked, then hardware (or software) as preferred, then provider order. HEVC and AV1 without any
/// encoder fall back to H.264 8-bit (bit rate scaled by the bits-per-pixel defaults), 10-bit without a 10-bit encoder
/// drops to 8-bit, and the size is capped to the highest codec level and to the encoder's maximum (aspect kept, even
/// sizes), the bit rate to the level's ceiling. Every adjustment carries a notice.</item>
/// </list>
/// </summary>
public static class EncoderSelector
{
public static EncoderSelection Select(EncodeSettings requested, IReadOnlyList<IVideoEncoderProvider> providers, EncoderHost host)
{
ArgumentNullException.ThrowIfNull(requested);
ArgumentNullException.ThrowIfNull(providers);
var notices = new List<EncoderNotice>();
return VideoCodecInfo.IsManaged(requested.Codec)
? SelectManaged(requested, providers, notices)
: SelectVideo(requested, providers, host, notices);
}
private static EncoderSelection SelectManaged(EncodeSettings settings, IReadOnlyList<IVideoEncoderProvider> providers, List<EncoderNotice> notices)
{
var depths = ManagedEncoderProvider.BitDepths(settings.Codec);
if (depths.Count > 0 && !depths.Contains(settings.BitDepth))
{
var deeper = depths.Where(d => d >= settings.BitDepth).ToList();
var depth = deeper.Count > 0 ? deeper.Min() : depths.Max();
notices.Add(new EncoderNotice(EncoderNotices.BitDepthAdjusted, Invariant(settings.BitDepth), Invariant(depth)));
settings = settings with { BitDepth = depth };
}
foreach (var provider in providers)
{
if (!provider.CanEncode(settings)) continue;
return new EncoderSelection
{
Status = EncoderSelectionStatus.Ready,
Settings = settings,
Provider = provider,
Capability = provider.Capabilities.FirstOrDefault(c => c.Codec == settings.Codec),
Notices = notices,
};
}
notices.Add(new EncoderNotice(EncoderNotices.NoEncoder, settings.Codec.ToString()));
return new EncoderSelection { Status = EncoderSelectionStatus.Unavailable, Settings = settings, Notices = notices };
}
private static EncoderSelection SelectVideo(EncodeSettings settings, IReadOnlyList<IVideoEncoderProvider> providers, EncoderHost host, List<EncoderNotice> notices)
{
if (host == EncoderHost.Server)
{
notices.Add(new EncoderNotice(EncoderNotices.NeedsRenderNode, settings.Codec.ToString()));
return new EncoderSelection { Status = EncoderSelectionStatus.NeedsRenderNode, Settings = settings, Notices = notices };
}
if (settings.Codec != VideoCodec.H264 && Candidates(providers, settings.Codec).Count == 0)
{
notices.Add(new EncoderNotice(EncoderNotices.FallbackToH264, settings.Codec.ToString()));
var factor = ExportPreset.DefaultBitsPerPixel(VideoCodec.H264) / ExportPreset.DefaultBitsPerPixel(settings.Codec);
settings = settings with
{
Codec = VideoCodec.H264,
Profile = CodecProfile.H264High,
BitDepth = 8,
BitRate = (long)double.Round(settings.BitRate * factor),
};
}
if (settings.Codec == VideoCodec.H264 && settings.BitDepth != 8)
{
notices.Add(new EncoderNotice(EncoderNotices.BitDepthAdjusted, Invariant(settings.BitDepth), "8"));
settings = settings with { BitDepth = 8 };
}
var candidates = Candidates(providers, settings.Codec);
if (candidates.Count == 0)
{
notices.Add(new EncoderNotice(EncoderNotices.NoEncoder, settings.Codec.ToString()));
return new EncoderSelection { Status = EncoderSelectionStatus.Unavailable, Settings = settings, Notices = notices };
}
var wantsTenBit = settings.BitDepth > 8;
var ordered = candidates
.Select((c, order) => (c.Provider, c.Capability, Order: order))
.OrderByDescending(c => settings.EncoderName is not null && c.Capability.Name == settings.EncoderName)
.ThenByDescending(c => wantsTenBit && c.Capability.SupportsTenBit)
.ThenByDescending(c => c.Capability.Hardware == settings.PreferHardware)
.ThenBy(c => c.Order)
.ToList();
foreach (var (provider, capability, _) in ordered)
{
var local = new List<EncoderNotice>(notices);
var adjusted = Fit(settings, capability, local);
if (!provider.CanEncode(adjusted)) continue;
if (settings.PreferHardware && !capability.Hardware) local.Add(new EncoderNotice(EncoderNotices.SoftwareOnly, capability.Name));
var check = CodecLimits.Check(adjusted.Codec, adjusted.Width, adjusted.Height, adjusted.FrameRate.Value, adjusted.BitRate, adjusted.Profile);
return new EncoderSelection
{
Status = EncoderSelectionStatus.Ready,
Settings = adjusted,
Provider = provider,
Capability = capability,
Level = check.Level,
Notices = local,
};
}
notices.Add(new EncoderNotice(EncoderNotices.NoEncoder, settings.Codec.ToString()));
return new EncoderSelection { Status = EncoderSelectionStatus.Unavailable, Settings = settings, Notices = notices };
}
private static List<(IVideoEncoderProvider Provider, EncoderCapability Capability)> Candidates(IReadOnlyList<IVideoEncoderProvider> providers, VideoCodec codec) =>
[.. providers.SelectMany(p => p.Capabilities.Where(c => c.Codec == codec).Select(c => (p, c)))];
/// <summary>Applies bit-depth, level and encoder-size limits for one capability.</summary>
private static EncodeSettings Fit(EncodeSettings s, EncoderCapability capability, List<EncoderNotice> notices)
{
if (s.BitDepth > 8 && !capability.SupportsTenBit)
{
notices.Add(new EncoderNotice(EncoderNotices.TenBitUnavailable, capability.Name));
s = s with { BitDepth = 8, Profile = s.Profile == CodecProfile.HevcMain10 ? CodecProfile.HevcMain : s.Profile };
}
var even = (Width: s.Width & ~1, Height: s.Height & ~1);
s = s with { Width = int.Max(2, even.Width), Height = int.Max(2, even.Height) };
var fps = s.FrameRate.Value;
var check = CodecLimits.Check(s.Codec, s.Width, s.Height, fps, 0, s.Profile);
if (!check.Fits && check.SuggestedWidth > 0)
{
s = s with { Width = check.SuggestedWidth, Height = check.SuggestedHeight };
notices.Add(new EncoderNotice(EncoderNotices.ResolutionCappedByLevel, check.HighestLevel.Name, Size(s)));
}
if (s.Width > capability.MaxWidth || s.Height > capability.MaxHeight)
{
var scale = double.Min((double)capability.MaxWidth / s.Width, (double)capability.MaxHeight / s.Height);
var width = int.Max(2, (int)(s.Width * scale) & ~1);
var height = int.Max(2, (int)double.Round(width * (double)s.Height / s.Width / 2) * 2);
if (height > capability.MaxHeight) height = capability.MaxHeight & ~1;
s = s with { Width = width, Height = height };
notices.Add(new EncoderNotice(EncoderNotices.ResolutionCappedByEncoder, capability.Name, Size(s)));
}
var limits = CodecLimits.Check(s.Codec, s.Width, s.Height, fps, 0, s.Profile);
if (s.BitRate > limits.MaxBitRate)
{
s = s with { BitRate = limits.MaxBitRate };
notices.Add(new EncoderNotice(EncoderNotices.BitRateCapped, limits.HighestLevel.Name, Invariant(limits.MaxBitRate)));
}
return s;
}
private static string Size(EncodeSettings s) => string.Create(CultureInfo.InvariantCulture, $"{s.Width}×{s.Height}");
private static string Invariant(long value) => value.ToString(CultureInfo.InvariantCulture);
}
+145
View File
@@ -0,0 +1,145 @@
using Titano.Core.Video;
namespace Titano.Core.Export;
/// <summary>What a render will do, in the units the estimates need.</summary>
/// <param name="OutputFrames">Distinct output pictures (planned frames).</param>
/// <param name="OutputPeriods">Output frame periods (pictures repeated on constant-rate outputs).</param>
/// <param name="DurationSeconds">Video duration.</param>
/// <param name="Width">Output width.</param>
/// <param name="Height">Output height.</param>
/// <param name="WorkingPixels">Pixels of each decoded source frame.</param>
/// <param name="FlowFrames">Output frames that need optical flow (synthesised or motion-blurred).</param>
/// <param name="AnalysisFrames">Frames read by the preparation pass (0 when cached analysis covers everything).</param>
/// <param name="HardwareEncoder">True when a hardware encoder is expected.</param>
public sealed record ExportWorkload(
int OutputFrames,
int OutputPeriods,
double DurationSeconds,
int Width,
int Height,
long WorkingPixels,
int FlowFrames,
int AnalysisFrames,
bool HardwareEncoder);
/// <summary>Estimated output size and render time.</summary>
public sealed record ExportEstimate(long Bytes, TimeSpan Time);
/// <summary>
/// Throughput of the stages on this machine, in megapixels (or frames) per second. Defaults are conservative figures
/// for a 4-core desktop; <see cref="Calibrate"/> folds the measured time of a finished render into <see cref="Scale"/>.
/// </summary>
public sealed record ThroughputModel
{
public static ThroughputModel Default { get; } = new();
public double DecodeMegapixelsPerSecond { get; init; } = 80;
/// <summary>Exposure, geometry and stacking per working-size pixel.</summary>
public double ProcessMegapixelsPerSecond { get; init; } = 60;
/// <summary>Optical flow plus synthesis or blur per output pixel.</summary>
public double FlowMegapixelsPerSecond { get; init; } = 5;
public double AnalysisFramesPerSecond { get; init; } = 40;
public double HardwareEncodeMegapixelsPerSecond { get; init; } = 400;
public double SoftwareVideoEncodeMegapixelsPerSecond { get; init; } = 50;
public double JpegEncodeMegapixelsPerSecond { get; init; } = 60;
public double PngEncodeMegapixelsPerSecond { get; init; } = 12;
public double TiffEncodeMegapixelsPerSecond { get; init; } = 25;
public double GifEncodeMegapixelsPerSecond { get; init; } = 20;
/// <summary>Machine factor learnt from finished renders (2 = twice as fast as the defaults).</summary>
public double Scale { get; init; } = 1;
/// <summary>Moves <see cref="Scale"/> towards the ratio of a predicted to an actual render time.</summary>
/// <param name="weight">0 keeps the old scale, 1 adopts the new measurement entirely.</param>
public ThroughputModel Calibrate(TimeSpan predicted, TimeSpan actual, double weight = 0.5)
{
if (predicted <= TimeSpan.Zero || actual <= TimeSpan.Zero) return this;
var ratio = predicted.TotalSeconds / actual.TotalSeconds;
return this with { Scale = double.Clamp(Scale * double.Pow(ratio, double.Clamp(weight, 0, 1)), 0.02, 50) };
}
internal double EncodeMegapixelsPerSecond(VideoCodec codec, bool hardware) => codec switch
{
VideoCodec.H264 or VideoCodec.Hevc or VideoCodec.Av1 => hardware ? HardwareEncodeMegapixelsPerSecond : SoftwareVideoEncodeMegapixelsPerSecond,
VideoCodec.Mjpeg or VideoCodec.JpegSequence => JpegEncodeMegapixelsPerSecond,
VideoCodec.PngSequence or VideoCodec.Apng => PngEncodeMegapixelsPerSecond,
VideoCodec.Gif => GifEncodeMegapixelsPerSecond,
_ => TiffEncodeMegapixelsPerSecond,
};
}
/// <summary>
/// Output size and render time estimates for the Export tab. Video codecs: bit rate × duration plus 1 % container
/// overhead. Frame-based outputs: bits per pixel typical of photographic time-lapse content — JPEG by quality
/// (≈1 bpp at 50 to ≈9 bpp at 100), PNG 12/30 bpp (8/16-bit), TIFF-16 30 bpp, DNG 26 bpp, GIF 2.5 bpp for the first
/// frame and 1.2 bpp per difference frame, APNG 10 and 6 bpp — times the pictures written (constant-rate outputs repeat
/// held pictures).
/// </summary>
public static class ExportEstimator
{
private static readonly (int Quality, double Bpp)[] JpegBits = [(1, 0.3), (50, 1.0), (75, 1.6), (85, 2.2), (90, 2.8), (95, 4.0), (100, 9.0)];
public static ExportEstimate Estimate(ResolvedExport export, ExportWorkload workload, ThroughputModel? model = null)
{
ArgumentNullException.ThrowIfNull(export);
ArgumentNullException.ThrowIfNull(workload);
return new ExportEstimate(EstimateBytes(export, workload), EstimateTime(export.Codec, workload, model ?? ThroughputModel.Default));
}
public static long EstimateBytes(ResolvedExport export, ExportWorkload w)
{
ArgumentNullException.ThrowIfNull(export);
ArgumentNullException.ThrowIfNull(w);
double pixels = (double)w.Width * w.Height;
var bits = export.Codec switch
{
VideoCodec.H264 or VideoCodec.Hevc or VideoCodec.Av1 => export.EffectiveBitRate(w.Width, w.Height) * w.DurationSeconds * 1.01,
VideoCodec.Mjpeg => (JpegBitsPerPixel(export.Quality) * pixels + 24 * 8) * w.OutputPeriods,
VideoCodec.JpegSequence => JpegBitsPerPixel(export.Quality) * pixels * w.OutputPeriods,
VideoCodec.PngSequence => (export.BitDepth > 8 ? 30 : 12) * pixels * w.OutputPeriods,
VideoCodec.Tiff16Sequence => (export.BitDepth > 8 ? 30 : 12) * pixels * w.OutputPeriods,
VideoCodec.LinearDngSequence => 26 * pixels * w.OutputPeriods,
VideoCodec.Gif => w.OutputFrames > 0 ? (2.5 + 1.2 * (w.OutputFrames - 1)) * pixels : 0,
VideoCodec.Apng => w.OutputFrames > 0 ? (10 + 6.0 * (w.OutputFrames - 1)) * pixels : 0,
_ => 0,
};
return (long)double.Ceiling(bits / 8);
}
public static TimeSpan EstimateTime(VideoCodec codec, ExportWorkload w, ThroughputModel model)
{
ArgumentNullException.ThrowIfNull(w);
ArgumentNullException.ThrowIfNull(model);
var outputMp = (double)w.Width * w.Height / 1e6;
var workingMp = w.WorkingPixels / 1e6;
var seconds = w.AnalysisFrames / model.AnalysisFramesPerSecond
+ w.OutputFrames * (workingMp / model.DecodeMegapixelsPerSecond + workingMp / model.ProcessMegapixelsPerSecond
+ outputMp / model.EncodeMegapixelsPerSecond(codec, w.HardwareEncoder))
+ w.FlowFrames * outputMp / model.FlowMegapixelsPerSecond;
return TimeSpan.FromSeconds(seconds / model.Scale);
}
/// <summary>Typical JPEG bits per pixel at an IJG quality, piecewise linear between measured points.</summary>
public static double JpegBitsPerPixel(int quality)
{
quality = int.Clamp(quality, 1, 100);
for (var i = 1; i < JpegBits.Length; i++)
{
var (q1, b1) = JpegBits[i];
if (quality > q1) continue;
var (q0, b0) = JpegBits[i - 1];
return b0 + (b1 - b0) * (quality - q0) / (q1 - q0);
}
return JpegBits[^1].Bpp;
}
}
+153
View File
@@ -0,0 +1,153 @@
using System.Globalization;
using System.Text;
using Titano.Core.Naming;
using Titano.Core.Project;
using Titano.Core.Video;
namespace Titano.Core.Export;
/// <summary>Values of the export name tokens.</summary>
public sealed record ExportNameContext
{
/// <summary>Shoot date of the sequence (first capture), or the render date when unknown.</summary>
public required DateTime Date { get; init; }
public string? Title { get; init; }
/// <summary>Display name of the preset in the user's language ("Custom" for custom values).</summary>
public required string PresetName { get; init; }
public int Width { get; init; }
public int Height { get; init; }
public Rational FrameRate { get; init; } = new(30, 1);
public required VideoCodec Codec { get; init; }
}
/// <summary>An expanded export name and any template problems.</summary>
public sealed record ExportName(string Name, IReadOnlyList<TemplateError> Errors)
{
public bool IsValid => Errors.Count == 0;
}
/// <summary>
/// Output names from <see cref="Project.ExportSettings.NameTemplate"/> (BRIEF §11.5). Tokens: <c>{date}</c> (optionally
/// <c>{date:yyyyMMdd}</c>), <c>{title}</c>, <c>{preset}</c>, <c>{width}</c>, <c>{height}</c>, <c>{fps}</c>, <c>{codec}</c>;
/// <c>{{</c>/<c>}}</c> are literal braces. The result is sanitised like <see cref="PathTemplate"/>; an existing file or
/// folder gets a " (2)", " (3)"… suffix.
/// </summary>
public static class ExportNaming
{
public static IReadOnlyList<string> Tokens { get; } = ["date", "title", "preset", "width", "height", "fps", "codec"];
/// <summary>Name used when a template expands to nothing.</summary>
public const string FallbackName = "Render";
/// <summary>Short, file-name safe codec label ("H.264", "HEVC", "PNG"…).</summary>
public static string CodecLabel(VideoCodec codec) => codec switch
{
VideoCodec.H264 => "H.264",
VideoCodec.Hevc => "HEVC",
VideoCodec.Av1 => "AV1",
VideoCodec.Mjpeg => "MJPEG",
VideoCodec.JpegSequence => "JPEG",
VideoCodec.PngSequence => "PNG",
VideoCodec.Tiff16Sequence => "TIFF",
VideoCodec.LinearDngSequence => "DNG",
VideoCodec.Gif => "GIF",
VideoCodec.Apng => "APNG",
_ => codec.ToString(),
};
/// <summary>Expands <paramref name="template"/> into a sanitised name without extension.</summary>
public static ExportName Expand(string template, ExportNameContext context)
{
ArgumentNullException.ThrowIfNull(template);
ArgumentNullException.ThrowIfNull(context);
var errors = new List<TemplateError>();
var sb = new StringBuilder();
for (var i = 0; i < template.Length; i++)
{
var c = template[i];
if ((c == '{' || c == '}') && i + 1 < template.Length && template[i + 1] == c)
{
sb.Append(c);
i++;
continue;
}
if (c == '}')
{
errors.Add(new TemplateError(i, "UnopenedBrace", null));
continue;
}
if (c != '{')
{
sb.Append(c);
continue;
}
var close = template.IndexOf('}', i + 1);
if (close < 0)
{
errors.Add(new TemplateError(i, "UnclosedBrace", null));
sb.Append(template, i, template.Length - i);
break;
}
var body = template[(i + 1)..close];
var colon = body.IndexOf(':', StringComparison.Ordinal);
var name = (colon < 0 ? body : body[..colon]).Trim().ToLowerInvariant();
var format = colon < 0 ? null : body[(colon + 1)..];
if (Value(name, format, context) is { } value) sb.Append(value.Replace('/', '-').Replace('\\', '-'));
else errors.Add(new TemplateError(i, name.Length == 0 ? "EmptyToken" : "UnknownToken", name));
i = close;
}
var result = PathTemplate.SanitizeSegment(sb.ToString());
return new ExportName(result.Length == 0 ? FallbackName : result, errors);
}
/// <summary>
/// Full output path inside <paramref name="folder"/>: the expanded name plus the codec's extension, or the bare name
/// for image sequences (a folder), made unique against existing files and folders.
/// </summary>
public static string OutputPath(string folder, string template, ExportNameContext context)
{
ArgumentException.ThrowIfNullOrWhiteSpace(folder);
var name = Expand(template, context).Name;
var extension = VideoCodecInfo.DefaultContainer(context.Codec) == ContainerFormat.ImageSequence ? string.Empty : VideoCodecInfo.FileExtension(context.Codec);
return Unique(folder, name, extension);
}
/// <summary>
/// Output path of a project's export: <see cref="ExportSettings.Folder"/> or, when unset, the sequence's exports folder,
/// named by <see cref="ExportSettings.NameTemplate"/>.
/// </summary>
public static string OutputPath(ExportSettings settings, string sequenceExportsFolder, ExportNameContext context)
{
ArgumentNullException.ThrowIfNull(settings);
return OutputPath(string.IsNullOrWhiteSpace(settings.Folder) ? sequenceExportsFolder : settings.Folder, settings.NameTemplate, context);
}
/// <summary>"name.ext", or "name (2).ext", "name (3).ext"… when a file or folder of that name exists.</summary>
public static string Unique(string folder, string name, string extension)
{
for (var n = 1; ; n++)
{
var candidate = Path.Combine(folder, (n == 1 ? name : string.Create(CultureInfo.InvariantCulture, $"{name} ({n})")) + extension);
if (!File.Exists(candidate) && !Directory.Exists(candidate)) return candidate;
}
}
private static string? Value(string token, string? format, ExportNameContext c)
{
var inv = CultureInfo.InvariantCulture;
return token switch
{
"date" => c.Date.ToString(format ?? "yyyy-MM-dd", inv),
"title" => c.Title ?? string.Empty,
"preset" => c.PresetName,
"width" => c.Width.ToString(format, inv),
"height" => c.Height.ToString(format, inv),
"fps" => c.FrameRate.ToString(),
"codec" => CodecLabel(c.Codec),
_ => null,
};
}
}
+229
View File
@@ -0,0 +1,229 @@
using Titano.Core.Project;
using Titano.Core.Video;
namespace Titano.Core.Export;
/// <summary>Export values after applying a project's overrides to its preset (BRIEF §11.4).</summary>
public sealed record ResolvedExport
{
/// <summary>Id of the preset whose values these are, or <see cref="ExportResolver.CustomId"/>.</summary>
public required string PresetId { get; init; }
/// <summary>Id of the preset the overrides were applied to.</summary>
public required string BasePresetId { get; init; }
/// <summary>Localisation key of the effective preset's name; null when custom.</summary>
public string? NameKey { get; init; }
public bool IsCustom => PresetId == ExportResolver.CustomId;
public required VideoCodec Codec { get; init; }
public ContainerFormat Container => VideoCodecInfo.DefaultContainer(Codec);
public CodecProfile Profile { get; init; }
public int BitDepth { get; init; } = 8;
/// <summary>Output width; 0 derives it from the height and the aspect, or from the source.</summary>
public int Width { get; init; }
/// <summary>Output height; 0 derives it from the width and the aspect, or from the source.</summary>
public int Height { get; init; }
public Rational FrameRate { get; init; } = new(30, 1);
/// <summary>Fixed bit rate in bit/s; 0 = <see cref="BitsPerPixel"/> at the render size.</summary>
public long BitRate { get; init; }
public double BitsPerPixel { get; init; }
/// <summary>Key-frame distance in frames.</summary>
public int GopFrames { get; init; }
public int BFrames { get; init; }
public int Quality { get; init; } = 92;
public RateControl RateControl { get; init; } = RateControl.Vbr;
/// <summary>Specific encoder name requested by the user, or null.</summary>
public string? Encoder { get; init; }
/// <summary>Localisation keys of ignored or invalid override values.</summary>
public IReadOnlyList<string> Warnings { get; init; } = [];
/// <summary>Average bit rate for a render of <paramref name="width"/>×<paramref name="height"/>.</summary>
public long EffectiveBitRate(int width, int height)
{
if (BitRate > 0) return BitRate;
var bpp = BitsPerPixel > 0 ? BitsPerPixel : ExportPreset.DefaultBitsPerPixel(Codec);
return (long)double.Round(bpp * width * height * FrameRate.Value);
}
public EncodeSettings ToEncodeSettings(string outputPath, int width, int height) => new()
{
OutputPath = outputPath,
Codec = Codec,
Width = width,
Height = height,
FrameRate = FrameRate,
Profile = Profile,
BitDepth = BitDepth,
RateControl = RateControl,
BitRate = EffectiveBitRate(width, height),
Quality = Quality,
GopLength = GopFrames,
BFrames = BFrames,
EncoderName = Encoder,
};
}
/// <summary>
/// Applies <see cref="ExportOverrides"/> to the selected preset and names the result: the preset's id when the values
/// equal it (or equal another preset), <see cref="CustomId"/> otherwise. Editing any value therefore flips the name to
/// "Custom" and editing it back restores the preset name. Unknown or contradictory override values are ignored with a
/// warning key.
/// </summary>
public static class ExportResolver
{
public const string CustomId = "custom";
/// <summary>Preset used when none is selected, the stored id is unknown or the selection is "custom".</summary>
public const string DefaultPresetId = "1080p-h264";
public static ResolvedExport Resolve(ExportSettings settings, IReadOnlyList<ExportPreset>? presets = null)
{
ArgumentNullException.ThrowIfNull(settings);
presets ??= ExportPresets.BuiltIn;
var warnings = new List<string>();
var id = settings.Preset.Resolve(DefaultPresetId);
var basePreset = Find(presets, id) ?? Find(presets, DefaultPresetId) ?? presets.FirstOrDefault()
?? throw new ArgumentException("No presets", nameof(presets));
if (!basePreset.Id.Equals(id, StringComparison.OrdinalIgnoreCase) && !id.Equals(CustomId, StringComparison.OrdinalIgnoreCase))
warnings.Add("Export.Warning.UnknownPreset");
var values = Apply(FromPreset(basePreset), settings.Overrides, warnings);
var match = Matches(values, FromPreset(basePreset)) ? basePreset : presets.FirstOrDefault(p => Matches(values, FromPreset(p)));
return values with
{
PresetId = match?.Id ?? CustomId,
BasePresetId = basePreset.Id,
NameKey = match?.NameKey,
Warnings = warnings,
};
}
/// <summary>The preset's own values (no overrides).</summary>
public static ResolvedExport FromPreset(ExportPreset preset)
{
ArgumentNullException.ThrowIfNull(preset);
return new ResolvedExport
{
PresetId = preset.Id,
BasePresetId = preset.Id,
NameKey = preset.NameKey,
Codec = preset.Codec,
Profile = preset.Profile,
BitDepth = preset.BitDepth,
Width = preset.Width,
Height = preset.Height,
FrameRate = preset.FrameRate,
BitRate = preset.BitRate,
BitsPerPixel = preset.BitsPerPixel,
GopFrames = int.Max(1, (int)double.Round(preset.GopSeconds * preset.FrameRate.Value)),
BFrames = preset.BFrames,
Quality = preset.Quality,
};
}
/// <summary>Parses a codec name or alias ("h264", "H.265", "hevc", "png", "tiff16", "dng"…).</summary>
public static bool TryParseCodec(string? text, out VideoCodec codec)
{
codec = default;
if (string.IsNullOrWhiteSpace(text)) return false;
var key = text.Trim().ToLowerInvariant().Replace(".", string.Empty, StringComparison.Ordinal).Replace("-", string.Empty, StringComparison.Ordinal).Replace(" ", string.Empty, StringComparison.Ordinal);
VideoCodec? parsed = key switch
{
"h264" or "avc" => VideoCodec.H264,
"h265" or "hevc" => VideoCodec.Hevc,
"av1" => VideoCodec.Av1,
"mjpeg" or "mjpg" => VideoCodec.Mjpeg,
"jpeg" or "jpg" or "jpegsequence" => VideoCodec.JpegSequence,
"png" or "pngsequence" => VideoCodec.PngSequence,
"tiff" or "tif" or "tiff16" or "tiff16sequence" => VideoCodec.Tiff16Sequence,
"dng" or "lineardng" or "lineardngsequence" => VideoCodec.LinearDngSequence,
"gif" => VideoCodec.Gif,
"apng" => VideoCodec.Apng,
_ => null,
};
if (parsed is null) return false;
codec = parsed.Value;
return true;
}
private static ExportPreset? Find(IReadOnlyList<ExportPreset> presets, string id) =>
presets.FirstOrDefault(p => p.Id.Equals(id, StringComparison.OrdinalIgnoreCase));
private static ResolvedExport Apply(ResolvedExport v, ExportOverrides o, List<string> warnings)
{
if (o.Codec is not null)
{
if (TryParseCodec(o.Codec, out var codec))
{
if (codec != v.Codec) v = v with { Codec = codec, Profile = CodecProfile.Auto, BitRate = 0, BitsPerPixel = 0 };
}
else
{
warnings.Add("Export.Warning.UnknownCodec");
}
}
if (o.Container is not null && !ContainerMatches(o.Container, v.Container)) warnings.Add("Export.Warning.ContainerIgnored");
if (o.Profile is not null)
{
if (Enum.TryParse<CodecProfile>(o.Profile, ignoreCase: true, out var profile) && Enum.IsDefined(profile)) v = v with { Profile = profile };
else warnings.Add("Export.Warning.UnknownProfile");
}
if (o.BitDepth is { } depth) v = v with { BitDepth = depth };
if (o.Width is { } width) v = v with { Width = int.Max(0, width) };
if (o.Height is { } height) v = v with { Height = int.Max(0, height) };
if (o.FrameRate is not null)
{
if (FrameRateText.TryParse(o.FrameRate, out var rate))
{
// A preset's GOP is defined in seconds: keep its duration at the new rate unless the GOP is overridden too.
var seconds = v.GopFrames / v.FrameRate.Value;
v = v with { FrameRate = rate, GopFrames = int.Max(1, (int)double.Round(seconds * rate.Value)) };
}
else
{
warnings.Add("Export.Warning.UnknownFrameRate");
}
}
if (o.BitRate is { } bitRate) v = v with { BitRate = long.Max(0, bitRate) };
if (o.GopFrames is { } gop) v = v with { GopFrames = int.Max(1, gop) };
if (o.BFrames is { } bFrames) v = v with { BFrames = int.Max(0, bFrames) };
if (o.Quality is { } quality) v = v with { Quality = int.Clamp(quality, 1, 100) };
if (o.RateControl is not null)
{
if (Enum.TryParse<RateControl>(o.RateControl, ignoreCase: true, out var rc) && Enum.IsDefined(rc)) v = v with { RateControl = rc };
else warnings.Add("Export.Warning.UnknownRateControl");
}
if (o.Encoder is not null) v = v with { Encoder = string.IsNullOrWhiteSpace(o.Encoder) ? null : o.Encoder };
return v;
}
private static bool ContainerMatches(string text, ContainerFormat container) =>
Enum.TryParse<ContainerFormat>(text, ignoreCase: true, out var parsed) && parsed == container;
/// <summary>Equal export values; bit rates compare as effective rates when the size is fixed.</summary>
private static bool Matches(ResolvedExport a, ResolvedExport b)
{
if (a.Codec != b.Codec || a.Profile != b.Profile || a.BitDepth != b.BitDepth || a.Width != b.Width || a.Height != b.Height
|| !FrameRateText.AreEqual(a.FrameRate, b.FrameRate) || a.GopFrames != b.GopFrames || a.BFrames != b.BFrames
|| a.Quality != b.Quality || a.RateControl != b.RateControl || a.Encoder != b.Encoder) return false;
return a.Width > 0 && a.Height > 0
? a.EffectiveBitRate(a.Width, a.Height) == b.EffectiveBitRate(b.Width, b.Height)
: a.BitRate == b.BitRate && a.BitsPerPixel == b.BitsPerPixel;
}
}
+36
View File
@@ -0,0 +1,36 @@
using System.Globalization;
using Titano.Core.Video;
namespace Titano.Core.Export;
/// <summary>Frame rates as stored in project files: "num/den" ("24000/1001"), a decimal ("29.97") or an integer ("30").</summary>
public static class FrameRateText
{
/// <summary>Parses a frame rate; decimals near the NTSC rates map to their exact fractions.</summary>
public static bool TryParse(string? text, out Rational rate)
{
rate = default;
if (string.IsNullOrWhiteSpace(text)) return false;
var s = text.Trim();
var slash = s.IndexOf('/', StringComparison.Ordinal);
if (slash >= 0)
{
if (!int.TryParse(s.AsSpan(0, slash), NumberStyles.None, CultureInfo.InvariantCulture, out var num)
|| !int.TryParse(s.AsSpan(slash + 1), NumberStyles.None, CultureInfo.InvariantCulture, out var den)
|| num <= 0 || den <= 0) return false;
rate = new Rational(num, den);
return true;
}
if (!double.TryParse(s, NumberStyles.Float, CultureInfo.InvariantCulture, out var fps) || !(fps > 0 && fps <= 1000)) return false;
rate = Rational.FromFps(fps);
return true;
}
/// <summary>Canonical text: "num/den" for fractional rates, the integer otherwise.</summary>
public static string Format(Rational rate) => rate.Denominator == 1
? rate.Numerator.ToString(CultureInfo.InvariantCulture)
: string.Create(CultureInfo.InvariantCulture, $"{rate.Numerator}/{rate.Denominator}");
/// <summary>Exact rational equality (24000/1001 equals 48000/2002).</summary>
public static bool AreEqual(Rational a, Rational b) => (long)a.Numerator * b.Denominator == (long)b.Numerator * a.Denominator;
}
@@ -0,0 +1,410 @@
using System.Buffers.Binary;
using System.Text;
using Titano.Core.Codecs.Png;
using Titano.Core.Hashing;
using Titano.Core.Imaging;
using Titano.Core.Video;
namespace Titano.Core.Render.Diagnostics;
/// <summary>A composed animation frame (8-bit sRGB RGBA canvas) and how long it is shown.</summary>
internal sealed record AnimationFrame(byte[] Rgba, long Duration90k);
/// <summary>A decoded GIF or APNG used to verify rendered outputs.</summary>
internal sealed record AnimationInfo(int Width, int Height, IReadOnlyList<AnimationFrame> Frames, int? LoopCount)
{
public long Duration90k => Frames.Sum(f => f.Duration90k);
/// <summary>Frame <paramref name="index"/> as a linear-light RGB buffer (alpha dropped).</summary>
public ImageBuffer ToLinear(int index) => PixelConvert.FromInterleaved8(Frames[index].Rgba, Width, Height, 4, TransferFunction.Srgb, 3);
}
/// <summary>The structure of an MJPEG AVI: headers, the JPEG of every frame and the legacy index size.</summary>
internal sealed record AviInfo(int Width, int Height, Rational FrameRate, int HeaderFrames, int StreamFrames, IReadOnlyList<byte[]> Frames, int IndexEntries);
/// <summary>Bounds-checked big/little-endian reads; every violation is an <see cref="InvalidDataException"/>.</summary>
internal ref struct ByteCursor(ReadOnlySpan<byte> data)
{
private readonly ReadOnlySpan<byte> _data = data;
public int Position { get; set; }
public readonly int Remaining => _data.Length - Position;
public ReadOnlySpan<byte> Take(int count)
{
if (count < 0 || count > Remaining) throw new InvalidDataException($"Truncated data at offset {Position}");
var span = _data.Slice(Position, count);
Position += count;
return span;
}
public byte U8() => Take(1)[0];
public ushort U16Le() => BinaryPrimitives.ReadUInt16LittleEndian(Take(2));
public uint U32Le() => BinaryPrimitives.ReadUInt32LittleEndian(Take(4));
public uint U32Be() => BinaryPrimitives.ReadUInt32BigEndian(Take(4));
public string FourCc() => Encoding.ASCII.GetString(Take(4));
}
/// <summary>Reads AVI files written by <see cref="Video.Avi.AviMjpegWriter"/> (RIFF 'AVI ' plus 'AVIX' continuations).</summary>
internal static class AviReader
{
public static AviInfo Read(ReadOnlySpan<byte> data)
{
var cursor = new ByteCursor(data);
var frames = new List<byte[]>();
int width = 0, height = 0, headerFrames = 0, streamFrames = 0, index = 0;
var rate = default(Rational);
var first = true;
while (cursor.Remaining >= 12)
{
if (cursor.FourCc() != "RIFF") throw new InvalidDataException("RIFF expected");
var size = (int)cursor.U32Le();
var end = cursor.Position + size;
var type = cursor.FourCc();
if (type != (first ? "AVI " : "AVIX")) throw new InvalidDataException($"Unexpected RIFF type '{type}'");
Walk(ref cursor, end, frames, ref width, ref height, ref headerFrames, ref streamFrames, ref rate, ref index);
cursor.Position = end + (size & 1);
first = false;
}
if (first) throw new InvalidDataException("No RIFF list");
if (width == 0 || rate.Numerator == 0) throw new InvalidDataException("Missing avih/strh headers");
return new AviInfo(width, height, rate, headerFrames, streamFrames, frames, index);
}
private static void Walk(ref ByteCursor cursor, int end, List<byte[]> frames, ref int width, ref int height, ref int headerFrames,
ref int streamFrames, ref Rational rate, ref int index)
{
while (cursor.Position + 8 <= end)
{
var id = cursor.FourCc();
var size = (int)cursor.U32Le();
if (size < 0 || cursor.Position + size > end) throw new InvalidDataException($"Chunk '{id}' overruns its list");
if (id == "LIST")
{
var listEnd = cursor.Position + size;
cursor.FourCc();
Walk(ref cursor, listEnd, frames, ref width, ref height, ref headerFrames, ref streamFrames, ref rate, ref index);
cursor.Position = listEnd + (size & 1);
continue;
}
var body = cursor.Take(size);
switch (id)
{
case "avih":
headerFrames = (int)BinaryPrimitives.ReadUInt32LittleEndian(body[16..]);
width = (int)BinaryPrimitives.ReadUInt32LittleEndian(body[32..]);
height = (int)BinaryPrimitives.ReadUInt32LittleEndian(body[36..]);
break;
case "strh":
var scale = (int)BinaryPrimitives.ReadUInt32LittleEndian(body[20..]);
var rateValue = (int)BinaryPrimitives.ReadUInt32LittleEndian(body[24..]);
if (scale <= 0 || rateValue <= 0) throw new InvalidDataException("Invalid stream rate");
rate = new Rational(rateValue, scale);
streamFrames = (int)BinaryPrimitives.ReadUInt32LittleEndian(body[32..]);
break;
case "00dc":
if (size < 4 || body[0] != 0xFF || body[1] != 0xD8) throw new InvalidDataException("Video chunk is not a JPEG");
frames.Add(body.ToArray());
break;
case "idx1":
index = size / 16;
break;
}
cursor.Position += size & 1;
}
}
}
/// <summary>GIF89a decoder with frame composition (disposal 0–3, transparency) for output verification.</summary>
internal static class GifReader
{
public static AnimationInfo Decode(ReadOnlySpan<byte> data)
{
var cursor = new ByteCursor(data);
var signature = Encoding.ASCII.GetString(cursor.Take(6));
if (signature is not ("GIF89a" or "GIF87a")) throw new InvalidDataException("Not a GIF");
int width = cursor.U16Le(), height = cursor.U16Le();
var packed = cursor.U8();
cursor.Take(2);
if (width == 0 || height == 0) throw new InvalidDataException("Empty logical screen");
var global = (packed & 0x80) != 0 ? cursor.Take(3 << ((packed & 7) + 1)).ToArray() : null;
var canvas = new byte[width * height * 4];
var frames = new List<AnimationFrame>();
int? loop = null;
int delay = 0, disposal = 0, transparent = -1;
while (true)
{
var block = cursor.U8();
if (block == 0x3B) break;
if (block == 0x21)
{
var label = cursor.U8();
if (label == 0xF9)
{
if (cursor.U8() != 4) throw new InvalidDataException("Bad graphic control extension");
var flags = cursor.U8();
delay = cursor.U16Le();
var index = cursor.U8();
disposal = (flags >> 2) & 7;
transparent = (flags & 1) != 0 ? index : -1;
if (cursor.U8() != 0) throw new InvalidDataException("Unterminated graphic control extension");
continue;
}
var payload = SubBlocks(ref cursor);
if (label == 0xFF && payload.Length >= 14 && Encoding.ASCII.GetString(payload, 0, 11) == "NETSCAPE2.0") loop = payload[12] | payload[13] << 8;
continue;
}
if (block != 0x2C) throw new InvalidDataException($"Unexpected block 0x{block:X2}");
int left = cursor.U16Le(), top = cursor.U16Le(), w = cursor.U16Le(), h = cursor.U16Le();
var imagePacked = cursor.U8();
if (left + w > width || top + h > height || w == 0 || h == 0) throw new InvalidDataException("Frame outside the logical screen");
if ((imagePacked & 0x40) != 0) throw new InvalidDataException("Interlaced frames are not verified");
var table = (imagePacked & 0x80) != 0 ? cursor.Take(3 << ((imagePacked & 7) + 1)).ToArray() : global
?? throw new InvalidDataException("No colour table");
var minCode = cursor.U8();
if (minCode is < 2 or > 8) throw new InvalidDataException("Bad LZW code size");
var indices = Lzw(SubBlocks(ref cursor), minCode, w * h);
var saved = disposal == 3 ? (byte[])canvas.Clone() : null;
for (var y = 0; y < h; y++)
{
for (var x = 0; x < w; x++)
{
var i = indices[y * w + x];
if (i == transparent) continue;
if (i * 3 + 2 >= table.Length) throw new InvalidDataException("Index outside the colour table");
var o = ((top + y) * width + left + x) * 4;
canvas[o] = table[i * 3];
canvas[o + 1] = table[i * 3 + 1];
canvas[o + 2] = table[i * 3 + 2];
canvas[o + 3] = 255;
}
}
frames.Add(new AnimationFrame((byte[])canvas.Clone(), delay * 900L));
if (disposal == 2)
{
for (var y = 0; y < h; y++) canvas.AsSpan(((top + y) * width + left) * 4, w * 4).Clear();
}
else if (saved is not null)
{
canvas = saved;
}
delay = 0;
disposal = 0;
transparent = -1;
}
return new AnimationInfo(width, height, frames, loop);
}
private static byte[] SubBlocks(ref ByteCursor cursor)
{
using var buffer = new MemoryStream();
while (true)
{
var length = cursor.U8();
if (length == 0) return buffer.ToArray();
buffer.Write(cursor.Take(length));
}
}
/// <summary>Variable-length LZW (GIF flavour: clear/end codes, codes up to 12 bits, deferred clear allowed).</summary>
private static byte[] Lzw(byte[] data, int minCode, int count)
{
var output = new byte[count];
var prefix = new short[4096];
var suffix = new byte[4096];
var stack = new byte[4097];
int clear = 1 << minCode, end = clear + 1;
int size = minCode + 1, next = end + 1, previous = -1, written = 0;
byte first = 0;
long bits = 0;
var bitCount = 0;
var pos = 0;
while (written < count)
{
while (bitCount < size && pos < data.Length)
{
bits |= (long)data[pos++] << bitCount;
bitCount += 8;
}
if (bitCount < size) throw new InvalidDataException("Image data ends early");
var code = (int)(bits & ((1 << size) - 1));
bits >>= size;
bitCount -= size;
if (code == clear)
{
size = minCode + 1;
next = end + 1;
previous = -1;
continue;
}
if (code == end) break;
int top = 0, current = code;
if (previous < 0)
{
if (code >= clear) throw new InvalidDataException("First code is not a literal");
first = (byte)code;
output[written++] = first;
previous = code;
continue;
}
if (code > next || (code == next && next >= 4096)) throw new InvalidDataException("Invalid LZW code");
if (code == next)
{
stack[top++] = first;
current = previous;
}
while (current >= clear)
{
stack[top++] = suffix[current];
current = prefix[current];
}
first = (byte)current;
stack[top++] = first;
while (top > 0 && written < count) output[written++] = stack[--top];
if (next < 4096)
{
prefix[next] = (short)previous;
suffix[next] = first;
next++;
if (next == 1 << size && size < 12) size++;
}
previous = code;
}
if (written < count) throw new InvalidDataException("Image data ends early");
return output;
}
}
/// <summary>APNG decoder for output verification: chunk CRCs, the shared sequence counter, fcTL/fdAT layout, and
/// composition with every dispose and blend operation (each frame is decoded through <see cref="PngDecoder"/>).</summary>
internal static class ApngReader
{
private static readonly byte[] Signature = [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A];
private sealed record Control(int Width, int Height, int X, int Y, long Duration90k, byte Dispose, byte Blend)
{
public List<byte[]> Data { get; } = [];
}
public static AnimationInfo Decode(ReadOnlySpan<byte> data)
{
var cursor = new ByteCursor(data);
if (!cursor.Take(8).SequenceEqual(Signature)) throw new InvalidDataException("Not a PNG");
byte[]? ihdr = null;
int? declaredFrames = null, plays = null;
var controls = new List<Control>();
var sequence = 0u;
while (true)
{
var length = (int)cursor.U32Be();
if (length < 0) throw new InvalidDataException("Chunk too long");
var typeAndBody = cursor.Take(4 + length);
if (Crc32.Compute(typeAndBody) != cursor.U32Be()) throw new InvalidDataException("Chunk CRC mismatch");
var type = Encoding.ASCII.GetString(typeAndBody[..4]);
var body = typeAndBody[4..];
switch (type)
{
case "IHDR":
ihdr = body.ToArray();
break;
case "acTL":
declaredFrames = (int)BinaryPrimitives.ReadUInt32BigEndian(body);
plays = (int)BinaryPrimitives.ReadUInt32BigEndian(body[4..]);
break;
case "fcTL":
Expect(ref sequence, body);
var num = BinaryPrimitives.ReadUInt16BigEndian(body[20..]);
var den = BinaryPrimitives.ReadUInt16BigEndian(body[22..]);
controls.Add(new Control(
(int)BinaryPrimitives.ReadUInt32BigEndian(body[4..]), (int)BinaryPrimitives.ReadUInt32BigEndian(body[8..]),
(int)BinaryPrimitives.ReadUInt32BigEndian(body[12..]), (int)BinaryPrimitives.ReadUInt32BigEndian(body[16..]),
num * 90000L / (den == 0 ? 100 : den), body[24], body[25]));
break;
case "IDAT":
if (controls.Count != 1) throw new InvalidDataException("The default image must be the first frame");
controls[0].Data.Add(body.ToArray());
break;
case "fdAT":
Expect(ref sequence, body);
if (controls.Count == 0) throw new InvalidDataException("fdAT before fcTL");
controls[^1].Data.Add(body[4..].ToArray());
break;
}
if (type == "IEND") break;
}
if (ihdr is null || declaredFrames is null) throw new InvalidDataException("Missing IHDR or acTL");
if (declaredFrames != controls.Count) throw new InvalidDataException($"acTL declares {declaredFrames} frames, {controls.Count} found");
var width = (int)BinaryPrimitives.ReadUInt32BigEndian(ihdr);
var height = (int)BinaryPrimitives.ReadUInt32BigEndian(ihdr.AsSpan(4));
var canvas = new byte[width * height * 4];
var frames = new List<AnimationFrame>(controls.Count);
foreach (var c in controls)
{
if (c.X + c.Width > width || c.Y + c.Height > height || c.Data.Count == 0) throw new InvalidDataException("Frame outside the canvas or without data");
var saved = c.Dispose == 2 ? (byte[])canvas.Clone() : null;
Compose(canvas, width, Region(ihdr, c), c);
frames.Add(new AnimationFrame((byte[])canvas.Clone(), c.Duration90k));
if (c.Dispose == 1)
{
for (var y = 0; y < c.Height; y++) canvas.AsSpan(((c.Y + y) * width + c.X) * 4, c.Width * 4).Clear();
}
else if (saved is not null)
{
canvas = saved;
}
}
return new AnimationInfo(width, height, frames, plays);
}
private static void Expect(ref uint sequence, ReadOnlySpan<byte> body)
{
if (BinaryPrimitives.ReadUInt32BigEndian(body) != sequence) throw new InvalidDataException($"Sequence number {sequence} expected");
sequence++;
}
/// <summary>Decodes one frame's data as a stand-alone PNG with the frame's size.</summary>
private static PngImage Region(byte[] ihdr, Control c)
{
using var png = new MemoryStream();
png.Write(Signature);
var header = (byte[])ihdr.Clone();
BinaryPrimitives.WriteUInt32BigEndian(header, (uint)c.Width);
BinaryPrimitives.WriteUInt32BigEndian(header.AsSpan(4), (uint)c.Height);
PngEncoder.WriteChunk(png, "IHDR", header);
foreach (var part in c.Data) PngEncoder.WriteChunk(png, "IDAT", part);
PngEncoder.WriteChunk(png, "IEND", []);
var image = PngDecoder.Decode(png.ToArray());
if (image.Warnings.Count > 0) throw new InvalidDataException("Frame data: " + image.Warnings[0]);
if (image.Pixels8 is null || image.Channels is not (3 or 4)) throw new InvalidDataException("Only 8-bit RGB/RGBA frames are verified");
return image;
}
private static void Compose(byte[] canvas, int width, PngImage frame, Control c)
{
var pixels = frame.Pixels8!;
var channels = frame.Channels;
for (var y = 0; y < c.Height; y++)
{
for (var x = 0; x < c.Width; x++)
{
var s = (y * c.Width + x) * channels;
var o = ((c.Y + y) * width + c.X + x) * 4;
var alpha = channels == 4 ? pixels[s + 3] : 255;
if (c.Blend == 1)
{
if (alpha == 0) continue;
if (alpha < 255) throw new InvalidDataException("Partial alpha blending is not verified");
}
canvas[o] = pixels[s];
canvas[o + 1] = pixels[s + 1];
canvas[o + 2] = pixels[s + 2];
canvas[o + 3] = (byte)alpha;
}
}
}
}
@@ -0,0 +1,105 @@
using Titano.Core.Imaging;
namespace Titano.Core.Render.Diagnostics;
/// <summary>
/// A continuous fractal value-noise texture (four octaves, periods 4–32 px, amplitude proportional to the period like
/// natural scenes) moved by a per-frame camera offset: exact sub-pixel motion and broadband texture for stabilisation,
/// flow and interpolation checks. Unlike per-pixel noise it passes the stabiliser's texture gate, and unlike sinusoids
/// it has no periodic ambiguity.
/// </summary>
public sealed class PatternFrameSource(int width, int height, int frameCount, Func<int, (double X, double Y)>? cameraMotion = null, double intervalSeconds = 10)
: IRenderFrameSource
{
private static readonly DateTime Start = new(2024, 6, 21, 21, 0, 0);
public int FrameCount { get; } = frameCount > 0 ? frameCount : throw new ArgumentOutOfRangeException(nameof(frameCount));
public int Width { get; } = width > 0 ? width : throw new ArgumentOutOfRangeException(nameof(width));
public int Height { get; } = height > 0 ? height : throw new ArgumentOutOfRangeException(nameof(height));
/// <summary>Content displacement of frame <paramref name="index"/> in full-resolution pixels.</summary>
public (double X, double Y) Offset(int index) => cameraMotion?.Invoke(index) ?? (0, 0);
/// <summary>Regular capture times, 1/250 s exposures.</summary>
public SourceFrameInfo[] Metadata()
{
var result = new SourceFrameInfo[FrameCount];
for (var i = 0; i < FrameCount; i++) result[i] = new SourceFrameInfo(Start.AddSeconds(i * intervalSeconds), 1.0 / 250, 10);
return result;
}
/// <summary>The texture at full resolution displaced by (<paramref name="dx"/>, <paramref name="dy"/>).</summary>
public ImageBuffer Render(double dx, double dy)
{
var image = new ImageBuffer(Width, Height, 3, clear: false);
var r = image.Plane(0);
var g = image.Plane(1);
var b = image.Plane(2);
for (var y = 0; y < Height; y++)
{
for (var x = 0; x < Width; x++)
{
double u = x - dx, v = y - dy;
var value = 0.06 + 0.4 * Texture(u, v);
var i = y * Width + x;
r[i] = (float)(value * (0.9 + 0.2 * ValueNoise(u / 48, v / 48, 101)));
g[i] = (float)value;
b[i] = (float)(value * (0.8 + 0.2 * ValueNoise(u / 48, v / 48, 102)));
}
}
return image;
}
/// <summary>Fractal value noise in [0, 1): octaves of period 4, 8, 16, 32 px weighted by their period.</summary>
private static double Texture(double x, double y)
{
double sum = 0, weights = 0;
for (var octave = 0; octave < 4; octave++)
{
double period = 4 << octave;
sum += period * ValueNoise(x / period, y / period, octave);
weights += period;
}
return sum / weights;
}
/// <summary>Hashed lattice values blended with a C1 smoothstep: continuous in x and y.</summary>
private static double ValueNoise(double x, double y, int seed)
{
var xi = (long)double.Floor(x);
var yi = (long)double.Floor(y);
var fx = x - xi;
var fy = y - yi;
fx = fx * fx * (3 - 2 * fx);
fy = fy * fy * (3 - 2 * fy);
var a = Hash(xi, yi, seed);
var b = Hash(xi + 1, yi, seed);
var c = Hash(xi, yi + 1, seed);
var d = Hash(xi + 1, yi + 1, seed);
var top = a + (b - a) * fx;
return top + (c + (d - c) * fx - top) * fy;
}
/// <summary>Uniform [0, 1) from a SplitMix64 mix of the lattice point (stable across processes).</summary>
private static double Hash(long x, long y, int seed)
{
var z = unchecked((ulong)x * 0x9E3779B97F4A7C15UL ^ (ulong)y * 0xC2B2AE3D27D4EB4FUL ^ (ulong)(uint)seed * 0x165667B19E3779F9UL);
z = unchecked((z ^ (z >> 30)) * 0xBF58476D1CE4E5B9UL);
z = unchecked((z ^ (z >> 27)) * 0x94D049BB133111EBUL);
z ^= z >> 31;
return (z >> 11) * (1.0 / (1UL << 53));
}
public ValueTask<ImageBuffer> GetFrameAsync(int index, int maxLongEdge, DecodePurpose purpose, CancellationToken cancellationToken)
{
ArgumentOutOfRangeException.ThrowIfNegative(index);
ArgumentOutOfRangeException.ThrowIfGreaterThanOrEqual(index, FrameCount);
cancellationToken.ThrowIfCancellationRequested();
var (dx, dy) = Offset(index);
var frame = Render(dx, dy);
if (maxLongEdge <= 0 || int.Max(Width, Height) <= maxLongEdge) return ValueTask.FromResult(frame);
using (frame) return ValueTask.FromResult(Resampler.Thumbnail(frame, maxLongEdge));
}
}
@@ -0,0 +1,219 @@
using System.Diagnostics;
using System.Globalization;
using Titano.Core.Codecs.Png;
using Titano.Core.Diagnostics.Synthetic;
using Titano.Core.Export;
using Titano.Core.Imaging;
using Titano.Core.Project;
using Titano.Core.Video;
using Titano.Core.Video.Managed;
namespace Titano.Core.Render.Diagnostics;
public enum SelfTestOutcome
{
Passed,
Failed,
/// <summary>The check needs something this machine does not have (e.g. an MP4 encoder).</summary>
Skipped,
}
/// <summary>Outcome of one self-test check; <see cref="Detail"/> carries the measured figures or the failure.</summary>
public sealed record SelfTestResult(string Id, string Group, string Description, SelfTestOutcome Outcome, string Detail, TimeSpan Elapsed);
/// <summary>What a check may use: its own empty folder, the encoders, and the run's cancellation.</summary>
public sealed record SelfTestContext(string WorkDirectory, IReadOnlyList<IVideoEncoderProvider> Encoders, IReadOnlyList<IVideoEncoderProvider> PlatformEncoders,
CancellationToken Cancellation);
/// <summary>One end-to-end check; it returns a short detail on success and throws on failure.</summary>
public sealed record SelfTestCheck(string Id, string Group, string Description, Func<SelfTestContext, Task<string>> Run);
public sealed record SelfTestOptions
{
/// <summary>Platform encoders tested in addition to the managed ones (the desktop passes Media Foundation).</summary>
public IReadOnlyList<IVideoEncoderProvider> PlatformEncoders { get; init; } = [];
/// <summary>Parent folder of the run's scratch folder (deleted afterwards); default the system temp folder.</summary>
public string? WorkDirectory { get; init; }
/// <summary>Run only checks whose id starts with one of these prefixes (all when empty).</summary>
public IReadOnlyList<string> Filters { get; init; } = [];
}
/// <summary>
/// The engine's end-to-end self-test (BRIEF §20.2, §20.4), shared by <c>Titano.Tools selftest</c> and the desktop
/// Settings page: render plans, export resolution and naming, encoder selection, managed codec round trips, renders of
/// small synthetic sequences into every managed format (and MP4 when a platform encoder is supplied) with their outputs
/// decoded back and compared, the processing modules measured on rendered frames, and cancellation, failure,
/// determinism and memory behaviour.
/// </summary>
public static partial class SelfTest
{
public static IReadOnlyList<SelfTestCheck> Checks { get; } = [.. PlanChecks(), .. ExportChecks(), .. CodecChecks(), .. RenderChecks(), .. ProcessingChecks(), .. RobustnessChecks()];
public static async Task<IReadOnlyList<SelfTestResult>> RunAsync(SelfTestOptions? options = null, IProgress<SelfTestResult>? progress = null,
CancellationToken cancellationToken = default)
{
options ??= new SelfTestOptions();
var root = Path.Combine(options.WorkDirectory ?? Path.GetTempPath(), "titano-selftest-" + Guid.NewGuid().ToString("N")[..8]);
Directory.CreateDirectory(root);
IVideoEncoderProvider[] encoders = [.. options.PlatformEncoders, new ManagedEncoderProvider()];
var results = new List<SelfTestResult>();
try
{
foreach (var check in Checks)
{
if (options.Filters.Count > 0 && !options.Filters.Any(f => check.Id.StartsWith(f, StringComparison.OrdinalIgnoreCase))) continue;
cancellationToken.ThrowIfCancellationRequested();
var directory = Path.Combine(root, check.Id);
Directory.CreateDirectory(directory);
var context = new SelfTestContext(directory, encoders, options.PlatformEncoders, cancellationToken);
var clock = Stopwatch.StartNew();
SelfTestOutcome outcome;
string detail;
try
{
detail = await check.Run(context).ConfigureAwait(false);
outcome = SelfTestOutcome.Passed;
}
catch (SkipException skip)
{
(outcome, detail) = (SelfTestOutcome.Skipped, skip.Message);
}
catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
{
throw;
}
catch (Exception ex)
{
(outcome, detail) = (SelfTestOutcome.Failed, ex is FailureException ? ex.Message : $"{ex.GetType().Name}: {ex.Message}");
}
var result = new SelfTestResult(check.Id, check.Group, check.Description, outcome, detail, clock.Elapsed);
results.Add(result);
progress?.Report(result);
}
}
finally
{
try
{
Directory.Delete(root, recursive: true);
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
Titano.Core.Diagnostics.Log.Warning("SelfTest", "Could not delete " + root, ex);
}
}
return results;
}
private sealed class FailureException(string message) : Exception(message);
private sealed class SkipException(string message) : Exception(message);
private static void Require(bool condition, string failure)
{
if (!condition) throw new FailureException(failure);
}
private static SelfTestCheck Check(string id, string description, Func<SelfTestContext, Task<string>> run) =>
new(id, id[..id.IndexOf('.', StringComparison.Ordinal)], description, run);
private static SelfTestCheck Check(string id, string description, Func<string> run) => Check(id, description, _ => Task.FromResult(run()));
private static string Invariant(FormattableString text) => text.ToString(CultureInfo.InvariantCulture);
/// <summary>No module and no knee: renders reproduce the source.</summary>
private static ProjectSettings Plain { get; } = new() { Exposure = new ExposureSettings { HighlightKnee = null } };
private static Auto<T> Manual<T>(T value) => new Auto<T>().WithManual(value);
private static SyntheticFrameSource Synthetic(int frames, Func<SyntheticSequenceOptions, SyntheticSequenceOptions>? configure = null,
Func<int, (double X, double Y)>? motion = null)
{
var options = new SyntheticSequenceOptions { FrameCount = frames, StartEv = 0, EndEv = 1, Seed = 5 };
return new SyntheticFrameSource(SyntheticSequence.Create(configure is null ? options : configure(options)), motion);
}
private static RenderInput Input(SyntheticFrameSource source, ProjectSettings? project = null) =>
new() { Source = source, Frames = source.Metadata(), Project = project ?? Plain };
/// <summary>A built-in preset's values at the synthetic frame size (or another size; 0×0 = source).</summary>
private static ResolvedExport Preset(string id, int width = 96, int height = 64) =>
ExportResolver.FromPreset(ExportPresets.Find(id)!) with { Width = width, Height = height };
private static RenderTarget Target(SelfTestContext context, ResolvedExport export, string name = "out") =>
new(export, Path.Combine(context.WorkDirectory, name + (export.Container == ContainerFormat.ImageSequence ? string.Empty : VideoCodecInfo.FileExtension(export.Codec))));
private static RenderPipeline Pipeline(SelfTestContext context) => new(context.Encoders);
/// <summary>Renders to a 16-bit PNG sequence and decodes every picture back (linear light).</summary>
private static async Task<List<ImageBuffer>> RenderDecodedAsync(SelfTestContext context, RenderInput input, ResolvedExport? export = null, string name = "decoded")
{
var target = Target(context, (export ?? Preset("png-sequence")) with { Codec = VideoCodec.PngSequence, BitDepth = 16 }, name);
await Pipeline(context).RenderAsync(input, target, cancellationToken: context.Cancellation).ConfigureAwait(false);
var frames = new List<ImageBuffer>();
foreach (var file in Directory.GetFiles(target.OutputPath).Order(StringComparer.Ordinal))
frames.Add(PngDecoder.DecodeToLinear(await File.ReadAllBytesAsync(file, context.Cancellation).ConfigureAwait(false)));
return frames;
}
private static void DisposeAll(IEnumerable<ImageBuffer> frames)
{
foreach (var f in frames) f.Dispose();
}
/// <summary>Peak signal-to-noise ratio of the 8-bit sRGB encodings, optionally inside a margin.</summary>
private static double Psnr(ImageBuffer expected, ImageBuffer actual, int margin = 0)
{
var a = PixelConvert.ToInterleaved8(expected, 3);
var b = PixelConvert.ToInterleaved8(actual, 3);
double sum = 0;
long count = 0;
for (var y = margin; y < expected.Height - margin; y++)
{
for (var i = (y * expected.Width + margin) * 3; i < (y * expected.Width + expected.Width - margin) * 3; i++)
{
sum += (a[i] - b[i]) * (a[i] - b[i]);
count++;
}
}
return sum == 0 ? double.PositiveInfinity : 10 * double.Log10(255.0 * 255 / (sum / count));
}
private static double Rms(IReadOnlyList<double> values)
{
var mean = values.Average();
return double.Sqrt(values.Sum(v => (v - mean) * (v - mean)) / values.Count);
}
/// <summary>RMS of the frame-to-frame change of (series − truth): flicker relative to the true curve.</summary>
private static double FrameToFrameResidual(IReadOnlyList<double> series, IReadOnlyList<double> truth)
{
double sum = 0;
for (var i = 1; i < series.Count; i++)
{
var d = series[i] - series[i - 1] - (truth[i] - truth[i - 1]);
sum += d * d;
}
return double.Sqrt(sum / (series.Count - 1));
}
/// <summary>Largest |series − truth − c| with c the mean offset (the measurement constant).</summary>
private static double MaxDeviation(IReadOnlyList<double> series, IReadOnlyList<double> truth)
{
var offset = 0.0;
for (var i = 0; i < series.Count; i++) offset += series[i] - truth[i];
offset /= series.Count;
var max = 0.0;
for (var i = 0; i < series.Count; i++) max = double.Max(max, double.Abs(series[i] - truth[i] - offset));
return max;
}
/// <summary>Synchronous progress sink (Progress&lt;T&gt; would post to the thread pool).</summary>
private sealed class Sink<T>(Action<T> report) : IProgress<T>
{
public void Report(T value) => report(value);
}
}
@@ -0,0 +1,317 @@
using Titano.Core.Codecs.Apng;
using Titano.Core.Codecs.Dng;
using Titano.Core.Codecs.Gif;
using Titano.Core.Codecs.Jpeg;
using Titano.Core.Codecs.Png;
using Titano.Core.Codecs.Tiff;
using Titano.Core.Export;
using Titano.Core.Imaging;
using Titano.Core.Metadata.Tiff;
using Titano.Core.Project;
using Titano.Core.Video;
using Titano.Core.Video.Avi;
namespace Titano.Core.Render.Diagnostics;
/// <summary>Plan, export, encoder-selection and codec checks.</summary>
public static partial class SelfTest
{
private static readonly DateTime Origin = new(2024, 6, 21, 19, 0, 0);
private static DateTime?[] Regular(int count) => [.. Enumerable.Range(0, count).Select(i => (DateTime?)Origin.AddSeconds(10 * i))];
private static ProjectSettings Timing(TimingMode mode, double? fit = null, IReadOnlyList<CurvePoint>? curve = null, IReadOnlyList<int>? excluded = null) => new()
{
Timing = new TimingSettings { Mode = Manual(mode), FitToSeconds = fit, RemapCurve = curve ?? [new(0, 0), new(1, 1)] },
ExcludedFrames = excluded ?? [],
};
private static void RequireExact(RenderPlan plan)
{
Require(plan.Frames.Sum(f => f.Duration90k) == plan.Duration90k, "durations do not add up to the total");
Require(plan.Duration90k == RenderPlan.TicksAt(plan.FrameRate, plan.SlotCount), "total differs from the period grid");
for (var k = 1; k < plan.Frames.Count; k++)
{
Require(plan.Frames[k].Start90k == plan.Frames[k - 1].Start90k + plan.Frames[k - 1].Duration90k, "frames are not contiguous");
Require(plan.Frames[k].SourcePosition >= plan.Frames[k - 1].SourcePosition, "source positions go backwards");
}
}
private static IEnumerable<SelfTestCheck> PlanChecks()
{
yield return Check("plan.constant", "Constant timing: one frame per period, exact durations", () =>
{
var plan = RenderPlan.Build(Regular(120), Timing(TimingMode.Constant), new Rational(24, 1));
RequireExact(plan);
Require(plan.Frames.Count == 120 && plan.Frames.All(f => f.Duration90k == 3750 && f.Slots == 1), "not one 1/24 s frame per source frame");
return Invariant($"120 frames, {plan.DurationSeconds} s");
});
yield return Check("plan.ntsc", "29.97 fps durations accumulate without drift", () =>
{
var plan = RenderPlan.Build(Regular(1001), Timing(TimingMode.Constant), Rational.Fps2997);
RequireExact(plan);
Require(plan.Duration90k == 1001 * 3003L, Invariant($"total {plan.Duration90k} ticks, expected {1001 * 3003L}"));
return Invariant($"1001 frames = {plan.Duration90k} ticks");
});
yield return Check("plan.excluded", "Excluded frames are skipped", () =>
{
var plan = RenderPlan.Build(Regular(30), Timing(TimingMode.Constant, excluded: [3, 4, 17]), new Rational(30, 1));
RequireExact(plan);
Require(plan.Frames.Count == 27 && !plan.Frames.Any(f => f.From is 3 or 4 or 17 || f.To is 3 or 4 or 17), "an excluded frame is used");
return "27 of 30 frames";
});
yield return Check("plan.adaptive.gap", "Adaptive: a doubled interval holds the frame for two periods", () =>
{
var times = Regular(20);
for (var i = 10; i < 20; i++) times[i] = times[i]!.Value.AddSeconds(10);
var plan = RenderPlan.Build(times, Timing(TimingMode.Adaptive), new Rational(24, 1));
RequireExact(plan);
Require(plan.Frames[9].Slots == 2 && plan.Frames[9].IsHeld, Invariant($"frame 9 lasts {plan.Frames[9].Slots} periods"));
return "held 2 periods";
});
yield return Check("plan.adaptive.pause", "Adaptive: a deliberate pause becomes a short cut", () =>
{
var times = Regular(20);
for (var i = 10; i < 20; i++) times[i] = times[i]!.Value.AddHours(2);
var plan = RenderPlan.Build(times, Timing(TimingMode.Adaptive), new Rational(24, 1));
RequireExact(plan);
var seconds = plan.Frames[9].Duration90k / 90000.0;
Require(seconds <= 0.25 && plan.IsCutBefore(10), Invariant($"pause shown for {seconds:0.###} s"));
return Invariant($"2 h pause shown for {seconds:0.###} s");
});
yield return Check("plan.interpolated", "Interpolated: a missing capture is synthesised half-way", () =>
{
var times = Regular(20);
for (var i = 10; i < 20; i++) times[i] = times[i]!.Value.AddSeconds(10);
var plan = RenderPlan.Build(times, Timing(TimingMode.Interpolated), new Rational(24, 1));
RequireExact(plan);
Require(plan.Frames.Count == 21 && plan.Frames.Count(f => f.IsInterpolated) == 1 && plan.Frames[10].SourcePosition == 9.5, "no synthesised frame at 9.5");
return "21 frames, 9.5 synthesised";
});
yield return Check("plan.remap.monotonic", "Remapped: positions are monotone even for a non-monotone curve", () =>
{
var plan = RenderPlan.Build(Regular(90), Timing(TimingMode.Remapped, curve: [new(0, 0), new(0.3, 0.6), new(0.5, 0.4), new(1, 1)]), new Rational(24, 1));
RequireExact(plan);
Require(plan.Warnings.Contains("Export.Plan.RemapNotMonotonic"), "the curve repair is not reported");
return Invariant($"{plan.Frames.Count} frames, {plan.Statistics.InterpolatedFrames} synthesised");
});
yield return Check("plan.fit", "Fit to duration rescales the plan exactly", () =>
{
var plan = RenderPlan.Build(Regular(300), Timing(TimingMode.Constant, fit: 5), new Rational(25, 1));
RequireExact(plan);
Require(plan.SlotCount == 125 && plan.Duration90k == 450_000, Invariant($"{plan.SlotCount} periods, {plan.DurationSeconds} s"));
return Invariant($"300 frames in {plan.DurationSeconds} s, speed {plan.Statistics.MaximumSpeed:0.##}×");
});
}
private static IEnumerable<SelfTestCheck> ExportChecks()
{
yield return Check("export.presets", "Every built-in preset resolves to itself and to valid encode settings", () =>
{
foreach (var preset in ExportPresets.BuiltIn)
{
var resolved = ExportResolver.Resolve(new ExportSettings { Preset = Manual(preset.Id) });
Require(resolved.PresetId == preset.Id && resolved.Warnings.Count == 0, preset.Id + " does not resolve to itself");
var settings = resolved.ToEncodeSettings("out", int.Max(2, preset.Width), int.Max(2, preset.Height));
Require(settings.GopLength >= 1 && (VideoCodecInfo.IsManaged(preset.Codec) || settings.BitRate > 0), preset.Id + " has invalid encode settings");
}
return Invariant($"{ExportPresets.BuiltIn.Count} presets");
});
yield return Check("export.custom", "Editing a value gives Custom; equal values restore the preset", () =>
{
var edited = ExportResolver.Resolve(new ExportSettings { Preset = Manual("1080p-h264"), Overrides = new ExportOverrides { Height = 1000 } });
var restored = ExportResolver.Resolve(new ExportSettings { Preset = Manual("1080p-h264"), Overrides = new ExportOverrides { Height = 1080, Codec = "H.264" } });
var other = ExportResolver.Resolve(new ExportSettings { Preset = Manual("1080p-h264"), Overrides = new ExportOverrides { FrameRate = "60" } });
Require(edited.IsCustom && restored.PresetId == "1080p-h264" && other.PresetId == "1080p60", "the Custom rule is broken");
return "custom ↔ preset";
});
yield return Check("export.naming", "Name tokens expand and are sanitised", () =>
{
var name = ExportNaming.Expand("{date} {title} - {preset} {width}x{height} {fps} {codec}", new ExportNameContext
{
Date = Origin,
Title = "Harbour: sunset",
PresetName = "4K",
Width = 3840,
Height = 2160,
FrameRate = Rational.Fps2997,
Codec = VideoCodec.Hevc,
});
Require(name.IsValid && name.Name == "2024-06-21 Harbour_ sunset - 4K 3840x2160 29.97 HEVC", "expanded to \"" + name.Name + "\"");
return name.Name;
});
yield return Check("export.collision", "Existing outputs get a numbered suffix", context =>
{
var nameContext = new ExportNameContext { Date = Origin, PresetName = "GIF", Codec = VideoCodec.Gif, Title = "Clip" };
var first = ExportNaming.OutputPath(context.WorkDirectory, "{title}", nameContext);
File.WriteAllBytes(first, [0]);
var second = ExportNaming.OutputPath(context.WorkDirectory, "{title}", nameContext);
Require(Path.GetFileName(first) == "Clip.gif" && Path.GetFileName(second) == "Clip (2).gif", "got " + Path.GetFileName(second));
return Task.FromResult(Path.GetFileName(second));
});
yield return Check("export.estimate", "Size and time estimates are consistent", () =>
{
var export = ExportResolver.FromPreset(ExportPresets.Find("4k-hevc")!);
var workload = new ExportWorkload(720, 720, 24, 3840, 2160, 3840L * 2160, 0, 0, true);
var bytes = ExportEstimator.EstimateBytes(export, workload);
var expected = export.EffectiveBitRate(3840, 2160) * 24 / 8.0 * 1.01;
Require(double.Abs(bytes - expected) <= 1, "video size is not bit rate × duration");
var time = ExportEstimator.EstimateTime(export.Codec, workload, ThroughputModel.Default);
var calibrated = ThroughputModel.Default.Calibrate(time, time / 2, 1);
Require(double.Abs(ExportEstimator.EstimateTime(export.Codec, workload, calibrated).TotalSeconds * 2 - time.TotalSeconds) < 1e-6, "calibration does not rescale");
return Invariant($"{bytes / 1e6:0.#} MB, {time.TotalSeconds:0} s");
});
yield return Check("select.managed", "Managed codecs select the managed encoder on clients and servers", context =>
{
foreach (var host in new[] { EncoderHost.Client, EncoderHost.Server })
{
var selection = EncoderSelector.Select(ExportResolver.FromPreset(ExportPresets.Find("png-sequence")!).ToEncodeSettings("x", 640, 360), context.Encoders, host);
Require(selection.IsReady && selection.Provider is Video.Managed.ManagedEncoderProvider, "PNG is not served by the managed encoder");
}
return Task.FromResult("managed");
});
yield return Check("select.server", "MP4 on the server needs a render node", context =>
{
var selection = EncoderSelector.Select(ExportResolver.FromPreset(ExportPresets.Find("1080p-h264")!).ToEncodeSettings("x.mp4", 1920, 1080), context.Encoders, EncoderHost.Server);
Require(selection.Status == EncoderSelectionStatus.NeedsRenderNode && selection.Notices.Any(n => n.Key == EncoderNotices.NeedsRenderNode), "no render-node notice");
return Task.FromResult(selection.Notices[0].Key);
});
yield return Check("select.client", "MP4 on this client: hardware preferred, HEVC falls back to H.264 with a reason", context =>
{
var hevc = EncoderSelector.Select(ExportResolver.FromPreset(ExportPresets.Find("4k-hevc")!).ToEncodeSettings("x.mp4", 3840, 2160), context.Encoders, EncoderHost.Client);
var hasHevc = context.Encoders.Any(p => p.Capabilities.Any(c => c.Codec == VideoCodec.Hevc));
var hasH264 = context.Encoders.Any(p => p.Capabilities.Any(c => c.Codec == VideoCodec.H264));
if (!hasHevc) Require(hevc.Notices.Count > 0 && hevc.Notices[0].Key == EncoderNotices.FallbackToH264, "no H.264 fallback notice");
if (!hasHevc && !hasH264) Require(hevc.Status == EncoderSelectionStatus.Unavailable, "an MP4 encoder was selected without any");
if (hasH264)
{
var h264 = EncoderSelector.Select(ExportResolver.FromPreset(ExportPresets.Find("1080p-h264")!).ToEncodeSettings("x.mp4", 1920, 1080), context.Encoders, EncoderHost.Client);
var hardware = context.Encoders.SelectMany(p => p.Capabilities).Any(c => c.Codec == VideoCodec.H264 && c.Hardware);
Require(h264.IsReady && h264.Capability!.Hardware == hardware, "hardware H.264 is not preferred");
return Task.FromResult($"{hevc.Status} via {hevc.Capability?.Name ?? "none"}; H.264 via {h264.Capability!.Name}");
}
return Task.FromResult(string.Join(", ", hevc.Notices.Select(n => n.Key)));
});
yield return Check("export.setup", "A render setup reports size, encoder, plan and estimates before rendering", context =>
{
var source = Synthetic(48, o => o with { Width = 480, Height = 320 });
var input = Input(source, Plain with { Exposure = new ExposureSettings { Deflicker = Manual(true) } });
var setup = Pipeline(context).Setup(input, Target(context, Preset("gif-preview", 480, 270)));
var estimate = setup.Estimate();
Require(setup.Encoder.IsReady && (setup.Geometry.OutputWidth, setup.Geometry.OutputHeight) == (480, 270) && setup.Plan.Frames.Count == 48
&& setup.NeedsPreparation && setup.Geometry.WorkingLongEdge == 480 && estimate.Bytes > 0 && estimate.Time > TimeSpan.Zero, "the setup is inconsistent");
return Task.FromResult(Invariant($"{estimate.Bytes / 1024} KiB, {estimate.Time.TotalSeconds:0.#} s estimated"));
});
yield return Check("select.limits", "Sizes beyond the codec levels are capped with a reason", () =>
{
var check = CodecLimits.Check(VideoCodec.Hevc, 7680, 4320, 240, 0);
Require(!check.Fits && check.SuggestedWidth > 0, "8K at 240 fps should exceed HEVC level 6.2");
Require(CodecLimits.Check(VideoCodec.Hevc, check.SuggestedWidth, check.SuggestedHeight, 240, 0).Fits, "the suggested size does not fit");
return Invariant($"8K240 → {check.SuggestedWidth}×{check.SuggestedHeight}");
});
}
private static ImageBuffer CodecFrame(int seed)
{
var image = new ImageBuffer(64, 48);
for (var y = 0; y < 48; y++)
{
for (var x = 0; x < 64; x++)
{
image[0, x, y] = (x + seed * 5) % 64 / 64f;
image[1, x, y] = y / 48f * 0.8f;
image[2, x, y] = (x * y + seed) % 29 / 28f * 0.6f;
}
}
return image;
}
private static IEnumerable<SelfTestCheck> CodecChecks()
{
yield return Check("codec.jpeg", "JPEG round trip", () =>
{
using var frame = CodecFrame(1);
using var back = JpegDecoder.DecodeToLinear(JpegEncoder.Encode(frame, new JpegEncodeOptions { Quality = 95, Subsampling = JpegSubsampling.Yuv444 }));
var psnr = Psnr(frame, back);
Require(psnr > 33, Invariant($"PSNR {psnr:0.#} dB"));
return Invariant($"PSNR {psnr:0.#} dB");
});
yield return Check("codec.png8", "PNG 8-bit round trip is exact", () =>
{
using var frame = CodecFrame(2);
Require(PngDecoder.Decode(PngEncoder.Encode(frame)).Pixels8!.AsSpan().SequenceEqual(PixelConvert.ToInterleaved8(frame, 3)), "pixels differ");
return "exact";
});
yield return Check("codec.png16", "PNG 16-bit round trip is exact", () =>
{
using var frame = CodecFrame(3);
Require(PngDecoder.Decode(PngEncoder.Encode(frame, 16)).Pixels16!.AsSpan().SequenceEqual(PixelConvert.ToInterleaved16(frame, 3)), "pixels differ");
return "exact";
});
yield return Check("codec.tiff16", "TIFF 16-bit round trip is exact", () =>
{
using var frame = CodecFrame(4);
var reader = TiffReader.Open(new MemoryStream(TiffWriter.Write(frame))) ?? throw new InvalidDataException("Not a TIFF");
var raster = TiffImageReader.ReadRaster(reader, reader.ReadChain()[0]);
Require(raster.Samples is not null && raster.Samples.AsSpan().SequenceEqual(PixelConvert.ToInterleaved16(frame, 3)), "samples differ");
return "exact";
});
yield return Check("codec.dng", "Linear DNG round trip within one 16-bit step", () =>
{
using var frame = CodecFrame(5);
using var back = TiffImageReader.Decode(LinearDngWriter.Write(frame, new LinearDngOptions { TileSize = 64 }));
var error = 0.0;
for (var i = 0; i < frame.Data.Length; i++) error = double.Max(error, double.Abs(frame.Data[i] - back.Data[i]));
Require(error <= 1.0 / 65535 + 1e-7, Invariant($"error {error:E2}"));
return Invariant($"max error {error * 65535:0.##} LSB");
});
yield return Check("codec.gif", "GIF frames and delays round trip", () =>
{
using var stream = new MemoryStream();
var gif = new GifEncoder(stream, 64, 48);
for (var i = 0; i < 3; i++)
{
using var f = CodecFrame(i);
gif.AddFrame(f, 9000 * (i + 1));
}
gif.Complete();
var animation = GifReader.Decode(stream.ToArray());
Require(animation.Frames.Count == 3 && animation.Duration90k == 54000 && animation.LoopCount == 0, "frames or delays differ");
using var expected = CodecFrame(2);
using var decoded = animation.ToLinear(2);
var psnr = Psnr(expected, decoded);
Require(psnr > 25, Invariant($"PSNR {psnr:0.#} dB"));
return Invariant($"3 frames, 0.6 s, PSNR {psnr:0.#} dB");
});
yield return Check("codec.apng", "APNG frames and delays round trip exactly", () =>
{
using var stream = new MemoryStream();
var apng = new ApngEncoder(stream, 64, 48);
for (var i = 0; i < 3; i++)
{
using var f = CodecFrame(i);
apng.AddFrame(f, 6000);
}
apng.Complete();
var animation = ApngReader.Decode(stream.ToArray());
using var expected = CodecFrame(1);
using var decoded = animation.ToLinear(1);
var psnr = Psnr(expected, decoded);
Require(animation.Frames.Count == 3 && animation.Duration90k == 18000 && psnr > 60, Invariant($"{animation.Frames.Count} frames, {animation.Duration90k} ticks, PSNR {psnr:0.#} dB"));
return "3 frames, exact delays";
});
yield return Check("codec.avi", "MJPEG AVI headers and indexes", () =>
{
using var stream = new MemoryStream();
var writer = new AviMjpegWriter(stream, 64, 48, Rational.Fps2997);
using var frame = CodecFrame(0);
var jpeg = JpegEncoder.Encode(frame);
for (var i = 0; i < 5; i++) writer.WriteFrame(jpeg);
writer.Complete();
var avi = AviReader.Read(stream.ToArray());
Require(avi.Frames.Count == 5 && avi.HeaderFrames == 5 && avi.StreamFrames == 5 && avi.IndexEntries == 5 && avi.FrameRate == Rational.Fps2997
&& (avi.Width, avi.Height) == (64, 48), "AVI structure differs");
return "5 frames, 30000/1001";
});
}
}
@@ -0,0 +1,558 @@
using Titano.Core.Analysis;
using Titano.Core.Codecs.Jpeg;
using Titano.Core.Codecs.Png;
using Titano.Core.Codecs.Tiff;
using Titano.Core.Diagnostics.Synthetic;
using Titano.Core.Export;
using Titano.Core.Imaging;
using Titano.Core.Imaging.Geometry;
using Titano.Core.Motion;
using Titano.Core.Project;
using Titano.Core.Video;
using Titano.Core.Video.Managed;
namespace Titano.Core.Render.Diagnostics;
/// <summary>Renders through the whole pipeline: output formats, processing modules and robustness.</summary>
public static partial class SelfTest
{
private static IEnumerable<SelfTestCheck> RenderChecks()
{
(string Id, string Preset, int Depth, double MinPsnr)[] formats =
[
("render.mjpeg", "mjpeg-avi", 8, 35), ("render.jpeg", "jpeg-sequence", 8, 35), ("render.png8", "png-sequence", 8, 60),
("render.png16", "png-sequence", 16, 60), ("render.tiff16", "tiff16-sequence", 16, 60), ("render.dng", "dng-sequence", 16, 60),
("render.gif", "gif-preview", 8, 25), ("render.apng", "apng", 8, 60),
];
foreach (var (id, preset, depth, minPsnr) in formats)
yield return Check(id, $"Render a synthetic sequence to {preset} ({depth}-bit) and decode it back", context => RenderFormatAsync(context, preset, depth, minPsnr));
yield return Check("render.mp4", "Render MP4 with this machine's platform encoders and inspect the file", RenderMp4Async);
yield return Check("render.held", "Held frames repeat on constant-rate outputs", async context =>
{
var source = Synthetic(10, o => o with { TimeShifts = [new SyntheticTimeShift(5, 20)] });
var project = Plain with { Timing = new TimingSettings { Mode = Manual(TimingMode.Adaptive) } };
var result = await Pipeline(context).RenderAsync(Input(source, project), Target(context, Preset("mjpeg-avi")), cancellationToken: context.Cancellation).ConfigureAwait(false);
var avi = AviReader.Read(await File.ReadAllBytesAsync(result.OutputPath, context.Cancellation).ConfigureAwait(false));
Require(result.FrameCount == 10 && avi.Frames.Count == 12, Invariant($"{result.FrameCount} pictures in {avi.Frames.Count} AVI frames"));
return "10 pictures, 12 frames";
});
}
private static async Task<string> RenderFormatAsync(SelfTestContext context, string presetId, int bitDepth, double minPsnr)
{
var source = Synthetic(12);
var export = Preset(presetId) with { BitDepth = bitDepth };
var target = Target(context, export);
var result = await Pipeline(context).RenderAsync(Input(source), target, cancellationToken: context.Cancellation).ConfigureAwait(false);
var entries = Directory.GetFileSystemEntries(context.WorkDirectory);
Require(entries.Length == 1 && entries[0] == target.OutputPath, "the folder holds more than the output");
Require(result.Bytes > 0 && result.FrameCount == 12, Invariant($"{result.FrameCount} frames, {result.Bytes} bytes"));
int count;
ImageBuffer decoded;
switch (export.Codec)
{
case VideoCodec.Mjpeg:
var avi = AviReader.Read(await File.ReadAllBytesAsync(target.OutputPath, context.Cancellation).ConfigureAwait(false));
Require(avi.FrameRate == export.FrameRate && (avi.Width, avi.Height) == (96, 64), "AVI headers differ");
count = avi.Frames.Count;
decoded = JpegDecoder.DecodeToLinear(avi.Frames[5]);
break;
case VideoCodec.Gif or VideoCodec.Apng:
var bytes = await File.ReadAllBytesAsync(target.OutputPath, context.Cancellation).ConfigureAwait(false);
var animation = export.Codec == VideoCodec.Gif ? GifReader.Decode(bytes) : ApngReader.Decode(bytes);
var expectedTicks = RenderPlan.TicksAt(export.FrameRate, 12);
Require(double.Abs(animation.Duration90k - expectedTicks) <= 900, Invariant($"duration {animation.Duration90k} ticks, expected {expectedTicks}"));
count = animation.Frames.Count;
decoded = animation.ToLinear(5);
break;
default:
var files = Directory.GetFiles(target.OutputPath).Order(StringComparer.Ordinal).ToArray();
var stem = Path.GetFileName(target.OutputPath);
Require(files.Select(Path.GetFileName).SequenceEqual(Enumerable.Range(1, files.Length).Select(i => ImageSequenceSession.FrameName(stem, i, VideoCodecInfo.FileExtension(export.Codec)))),
"frame files are not numbered 1…n");
count = files.Length;
var data = await File.ReadAllBytesAsync(files[5], context.Cancellation).ConfigureAwait(false);
decoded = export.Codec switch
{
VideoCodec.JpegSequence => JpegDecoder.DecodeToLinear(data),
VideoCodec.PngSequence => PngDecoder.DecodeToLinear(data),
_ => TiffImageReader.Decode(data),
};
break;
}
using (decoded)
using (var expected = source.Sequence.Render(5))
{
Require(count == 12, Invariant($"{count} pictures in the output"));
var psnr = Psnr(expected, decoded);
Require(psnr >= minPsnr, Invariant($"PSNR {psnr:0.#} dB < {minPsnr} dB"));
return Invariant($"{result.Bytes} bytes, PSNR {(double.IsPositiveInfinity(psnr) ? "∞" : psnr.ToString("0.#", System.Globalization.CultureInfo.InvariantCulture))} dB, {result.EncoderName}");
}
}
private static async Task<string> RenderMp4Async(SelfTestContext context)
{
var codecs = context.PlatformEncoders.SelectMany(p => p.Capabilities).Select(c => c.Codec).Where(c => !VideoCodecInfo.IsManaged(c)).Distinct().ToList();
if (codecs.Count == 0) throw new SkipException("no MP4 encoder on this machine");
var pipeline = new RenderPipeline(context.Encoders);
var details = new List<string>();
foreach (var codec in codecs)
{
var export = Preset("1080p-h264", 320, 180) with { Codec = codec, Profile = CodecProfile.Auto, BitRate = 0, BitsPerPixel = 0 };
var result = await pipeline.RenderAsync(Input(Synthetic(24)), Target(context, export, codec.ToString()), cancellationToken: context.Cancellation).ConfigureAwait(false);
var report = Mp4Inspector.Inspect(result.OutputPath);
Require(report.IsValid, codec + ": " + string.Join("; ", report.Errors));
Require(report.Codec == codec && report.FrameCount == 24 && (report.Width, report.Height) == (320, 180), Invariant($"{codec}: {report.Codec} {report.Width}×{report.Height}, {report.FrameCount} frames"));
Require(double.Abs(report.Duration.TotalSeconds - result.DurationSeconds) < 0.05, Invariant($"{codec}: duration {report.Duration.TotalSeconds:0.###} s"));
details.Add($"{codec} via {result.EncoderName}{(result.Hardware ? " (hardware)" : string.Empty)}");
}
return string.Join(", ", details);
}
private static IEnumerable<SelfTestCheck> ProcessingChecks()
{
yield return Check("proc.deflicker", "Deflicker on rendered frames: flicker −60 % or better, ramp kept within 0.05 EV (§20.4)", async context =>
{
var source = Synthetic(200, o => o with { Seed = 3, StartEv = -2, EndEv = 1, FlickerEv = 0.1 });
var project = Plain with { Exposure = new ExposureSettings { Deflicker = Manual(true), DeflickerWindow = Manual(21), HighlightKnee = null } };
var frames = await RenderDecodedAsync(context, Input(source, project)).ConfigureAwait(false);
var output = frames.Select(f => FrameStatistics.MeasureLogLuminance(f)).ToArray();
DisposeAll(frames);
var input = Enumerable.Range(0, 200).Select(i =>
{
using var f = source.Sequence.Render(i);
return FrameStatistics.MeasureLogLuminance(f);
}).ToArray();
var before = FrameToFrameResidual(input, source.Sequence.SceneEv);
var after = FrameToFrameResidual(output, source.Sequence.SceneEv);
var ramp = MaxDeviation(output, source.Sequence.SceneEv);
Require(1 - after / before >= 0.6, Invariant($"flicker reduced by {1 - after / before:P0} only"));
Require(ramp <= 0.05, Invariant($"ramp deviates by {ramp:0.###} EV"));
return Invariant($"flicker −{1 - after / before:P0}, ramp within {ramp:0.###} EV");
});
yield return Check("proc.holygrail", "Holy grail: no output step above 0.3 EV (§20.4)", async context =>
{
var source = Synthetic(80, o => o with { ExposureSteps = [new SyntheticExposureStep(40, 1.0)], StartEv = 0, EndEv = 0 });
var project = Plain with { Exposure = new ExposureSettings { HolyGrail = Manual(true), Deflicker = Manual(true), HighlightKnee = null } };
var frames = await RenderDecodedAsync(context, Input(source, project)).ConfigureAwait(false);
var output = frames.Select(f => FrameStatistics.MeasureLogLuminance(f)).ToArray();
DisposeAll(frames);
var step = output.Zip(output.Skip(1), (a, b) => double.Abs(b - a)).Max();
Require(step <= 0.32, Invariant($"largest step {step:0.###} EV"));
Require(double.Abs(output[^1] - output[0] + 1) <= 0.1, "the exposure step was not kept");
return Invariant($"largest step {step:0.###} EV");
});
yield return Check("proc.regions", "Region deflicker: land residual at most half of the global correction's", async context =>
{
var source = Synthetic(48, o => o with { SkyFlickerEv = 0.3, LandFlickerEv = 0.3, StartEv = 0, EndEv = 0 });
var land = new float[96 * 64];
for (var y = 0; y < 64; y++)
{
for (var x = 0; x < 96; x++) land[y * 96 + x] = source.Sequence.IsSky(x, y) || y + 0.5 < source.Sequence.HorizonRow(x + 0.5) + 2 ? 0 : 1;
}
async Task<double> LandResidualAsync(RegionMode mode, string name)
{
var project = Plain with { Exposure = new ExposureSettings { Deflicker = Manual(true), Regions = Manual(mode), HighlightKnee = null } };
var frames = await RenderDecodedAsync(context, Input(source, project), name: name).ConfigureAwait(false);
var series = frames.Select(f => FrameStatistics.MeasureLogLuminance(f, land)).ToArray();
DisposeAll(frames);
return Rms(series);
}
var global = await LandResidualAsync(RegionMode.Off, "global").ConfigureAwait(false);
var regions = await LandResidualAsync(RegionMode.Horizon, "regions").ConfigureAwait(false);
Require(regions <= 0.5 * global, Invariant($"land residual {regions:0.###} EV vs global {global:0.###} EV"));
return Invariant($"land residual {regions:0.###} vs {global:0.###} EV");
});
yield return Check("proc.whitebalance", "White-balance smoothing removes colour jitter", async context =>
{
var source = Synthetic(48, o => o with { WhiteBalanceJitter = 0.1 });
var project = Plain with { Exposure = new ExposureSettings { WhiteBalanceSmoothing = Manual(true), HighlightKnee = null } };
var frames = await RenderDecodedAsync(context, Input(source, project)).ConfigureAwait(false);
static double Ratio(ImageBuffer f)
{
var stats = FrameStatistics.Measure(f);
return double.Log2(stats.MeanRed / stats.MeanGreen);
}
var after = frames.Select(Ratio).ToArray();
DisposeAll(frames);
var before = Enumerable.Range(0, 48).Select(i =>
{
using var f = source.Sequence.Render(i);
return Ratio(f);
}).ToArray();
static double Jitter(double[] r) => double.Sqrt(r.Zip(r.Skip(1), (a, b) => (b - a) * (b - a)).Average());
Require(Jitter(after) < 0.3 * Jitter(before), Invariant($"R/G jitter {Jitter(before):0.####} → {Jitter(after):0.####}"));
return Invariant($"R/G jitter {Jitter(before):0.###} → {Jitter(after):0.####}");
});
yield return Check("proc.offset", "Exposure offset +1 EV doubles linear values", async context =>
{
var source = Synthetic(2);
var plain = await RenderDecodedAsync(context, Input(source), name: "plain").ConfigureAwait(false);
var brighter = await RenderDecodedAsync(context, Input(source, Plain with { Exposure = new ExposureSettings { ExposureOffsetEv = 1, HighlightKnee = null } }), name: "bright")
.ConfigureAwait(false);
var error = 0.0;
for (var i = 0; i < plain[0].Data.Length; i++) error = double.Max(error, double.Abs(2 * plain[0].Data[i] - brighter[0].Data[i]) / (1e-3 + brighter[0].Data[i]));
DisposeAll(plain);
DisposeAll(brighter);
Require(error < 0.01, Invariant($"relative error {error:P2}"));
return Invariant($"relative error {error:P3}");
});
yield return Check("proc.knee", "The highlight knee keeps values below 1 and leaves shadows alone", async context =>
{
var source = Synthetic(2, o => o with { StartEv = 2, EndEv = 2 });
var hard = await RenderDecodedAsync(context, Input(source), name: "hard").ConfigureAwait(false);
var knee = await RenderDecodedAsync(context, Input(source, Plain with { Exposure = new ExposureSettings { HighlightKnee = 0.8 } }), name: "knee").ConfigureAwait(false);
var clipped = hard[0].Data.ToArray().Count(v => v >= 0.9999f);
var top = knee[0].Data.ToArray().Max();
var shadows = true;
for (var i = 0; i < hard[0].Data.Length; i++)
{
if (hard[0].Data[i] < 0.5f) shadows &= double.Abs(hard[0].Data[i] - knee[0].Data[i]) < 1e-4;
}
DisposeAll(hard);
DisposeAll(knee);
Require(clipped > 0 && top < 0.9999f && shadows, Invariant($"{clipped} clipped samples without knee, max {top:0.####} with it"));
return Invariant($"{clipped} clipped samples → max {top:0.###}");
});
yield return Check("proc.aspect", "A square export crops the centre of a 3:2 frame", async context =>
{
var source = Synthetic(3);
var frames = await RenderDecodedAsync(context, Input(source), Preset("png-sequence", 64, 64)).ConfigureAwait(false);
using var reference = source.Sequence.Render(1);
using var expected = GeometryStage.Apply(reference, new GeometrySettings { Crop = new RectD(16, 0, 64, 64), OutputWidth = 64, OutputHeight = 64 });
var psnr = Psnr(expected, frames[1]);
DisposeAll(frames);
Require(psnr > 60, Invariant($"PSNR {psnr:0.#} dB"));
return "centre 64×64";
});
yield return Check("proc.crop", "The camera crop selects its region at source size", async context =>
{
var source = Synthetic(3);
var project = Plain with { Camera = new CameraSettings { Crop = [0.5, 0.5, 0.5, 0.5] } };
var frames = await RenderDecodedAsync(context, Input(source, project), Preset("png-sequence", 0, 0)).ConfigureAwait(false);
using var reference = source.Sequence.Render(1);
using var expected = GeometryStage.Apply(reference, new GeometrySettings { Crop = new RectD(48, 32, 48, 32) });
var size = (frames[1].Width, frames[1].Height);
var psnr = Psnr(expected, frames[1]);
DisposeAll(frames);
Require(size == (48, 32) && psnr > 60, Invariant($"{size}, PSNR {psnr:0.#} dB"));
return "quarter 48×32";
});
yield return Check("proc.zoom", "Virtual-camera zoom matches a direct crop and doubles the decode size", async context =>
{
var source = Synthetic(3, o => o with { Width = 480, Height = 320 });
var project = Plain with { Camera = new CameraSettings { Keyframes = [new CameraKey(0, 0.5, 0.5, 2, 0), new CameraKey(2, 0.5, 0.5, 2, 0)] } };
var frames = await RenderDecodedAsync(context, Input(source, project), Preset("png-sequence", 96, 64)).ConfigureAwait(false);
using var full = source.Sequence.Render(1);
using var expected = GeometryStage.Apply(full, new GeometrySettings { Crop = new RectD(120, 80, 240, 160), OutputWidth = 96, OutputHeight = 64 });
var psnr = Psnr(expected, frames[1]);
DisposeAll(frames);
Require(psnr > 28 && source.LargestRenderRequest == 192, Invariant($"PSNR {psnr:0.#} dB, decoded at {source.LargestRenderRequest} px"));
return Invariant($"PSNR {psnr:0.#} dB, decode {source.LargestRenderRequest} px");
});
yield return Check("proc.stabilize", "Stabilisation removes 90 % of the camera shake", async context =>
{
var random = new Random(11);
var shake = Enumerable.Range(0, 24).Select(_ => (X: random.NextDouble() * 6 - 3, Y: random.NextDouble() * 6 - 3)).ToArray();
var source = new PatternFrameSource(320, 192, 24, i => shake[i]);
var project = Plain with { Motion = new MotionSettings { Stabilize = Manual(true), StabilizeSmoothing = Manual(12.0) } };
var input = new RenderInput { Source = source, Frames = source.Metadata(), Project = project };
var frames = await RenderDecodedAsync(context, input, Preset("png-sequence", 0, 0)).ConfigureAwait(false);
using var stabilizer = new Stabilizer(320, 192);
var motions = frames.Select(f => stabilizer.AddFrame(f).Transform).Skip(1).ToArray();
DisposeAll(frames);
var after = double.Sqrt(motions.Average(m => m.Tx * m.Tx + m.Ty * m.Ty));
var before = double.Sqrt(Enumerable.Range(1, 23).Average(k => double.Pow(shake[k].X - shake[k - 1].X, 2) + double.Pow(shake[k].Y - shake[k - 1].Y, 2)));
Require(after <= 0.1 * before * 1.2, Invariant($"frame-to-frame shake {before:0.##} → {after:0.###} px"));
return Invariant($"shake {before:0.##} → {after:0.###} px");
});
yield return Check("proc.interpolate", "Synthesised in-betweens follow the motion", async context =>
{
var source = Synthetic(6, o => o with { StartEv = 0, EndEv = 0 }, i => (2.0 * i, 0));
var project = Plain with { Timing = new TimingSettings { Mode = Manual(TimingMode.Interpolated), FrameRate = Manual("15") } };
var frames = await RenderDecodedAsync(context, Input(source, project)).ConfigureAwait(false);
var truth = Synthetic(6, o => o with { StartEv = 0, EndEv = 0 }, i => (2.0 * i + 1, 0));
using var halfway = await truth.GetFrameAsync(2, 0, DecodePurpose.Render, context.Cancellation).ConfigureAwait(false);
var synthesised = Psnr(halfway, frames[5], 8);
var nearest = Psnr(halfway, frames[4], 8);
var count = frames.Count;
DisposeAll(frames);
Require(count == 12 && synthesised > 30 && synthesised > nearest + 5, Invariant($"{count} frames, {synthesised:0.#} dB vs nearest {nearest:0.#} dB"));
return Invariant($"{synthesised:0.#} dB (nearest whole frame {nearest:0.#} dB)");
});
yield return Check("proc.motionblur", "Motion blur smears along the motion and leaves still scenes alone", async context =>
{
var blur = new MotionSettings { MotionBlur = Manual(true), TargetShutterAngle = Manual(360.0) };
var moving = Synthetic(6, o => o with { StartEv = 0, EndEv = 0 }, i => (3.0 * i, 0));
var sharp = await RenderDecodedAsync(context, Input(moving), name: "sharp").ConfigureAwait(false);
var blurred = await RenderDecodedAsync(context, Input(moving, Plain with { Motion = blur }), name: "blurred").ConfigureAwait(false);
static double Gradient(ImageBuffer f, int dx, int dy)
{
double sum = 0;
var g = f.Plane(1);
for (var y = 8; y < f.Height - 8; y++)
{
for (var x = 8; x < f.Width - 8; x++) sum += double.Abs(g[y * f.Width + x] - g[(y + dy) * f.Width + x + dx]);
}
return sum;
}
var horizontal = Gradient(blurred[3], 1, 0) / Gradient(sharp[3], 1, 0);
var vertical = Gradient(blurred[3], 0, 1) / Gradient(sharp[3], 0, 1);
DisposeAll(sharp);
DisposeAll(blurred);
var still = Synthetic(4, o => o with { StartEv = 0, EndEv = 0 });
var a = await RenderDecodedAsync(context, Input(still), name: "still").ConfigureAwait(false);
var b = await RenderDecodedAsync(context, Input(still, Plain with { Motion = blur }), name: "still-blur").ConfigureAwait(false);
var stillPsnr = Psnr(a[2], b[2]);
DisposeAll(a);
DisposeAll(b);
Require(horizontal < 0.75 && vertical > horizontal + 0.1 && stillPsnr > 40, Invariant($"gradients ×{horizontal:0.##} along, ×{vertical:0.##} across; still {stillPsnr:0.#} dB"));
return Invariant($"gradient ×{horizontal:0.##} along, ×{vertical:0.##} across");
});
yield return Check("proc.median", "A median stack removes a one-frame transient", async context =>
{
var source = Synthetic(9, o => o with { StartEv = 0, EndEv = 0 });
var project = Plain with { Stack = new StackSettings { Mode = StackSetting.Median, Length = 5 } };
var input = Input(source, project) with { Source = new TransientSource(source, 4) };
var frames = await RenderDecodedAsync(context, input).ConfigureAwait(false);
using var clean = source.Sequence.Render(4);
var psnr = Psnr(clean, frames[4]);
DisposeAll(frames);
Require(psnr > 45, Invariant($"PSNR {psnr:0.#} dB"));
return "transient removed";
});
yield return Check("proc.startrails", "Star-trail luminance never decreases on 99 % of steps (§20.4)", async context =>
{
var source = Synthetic(16, o => o with { StarField = true, StarCount = 60, StartEv = 0, EndEv = 0 }, i => (1.0 * i, 0.5 * i));
var project = Plain with { Stack = new StackSettings { Mode = StackSetting.StarTrails, Length = 0 } };
var frames = await RenderDecodedAsync(context, Input(source, project)).ConfigureAwait(false);
var luminance = frames.Select(f => FrameStatistics.MeasureLogLuminance(f, default, 0, 0)).ToArray();
DisposeAll(frames);
var rising = luminance.Zip(luminance.Skip(1), (a, b) => b >= a - 1e-9).Count(r => r);
Require(rising >= 0.99 * (luminance.Length - 1), Invariant($"{rising} of {luminance.Length - 1} steps non-decreasing"));
return Invariant($"{rising}/{luminance.Length - 1} steps non-decreasing");
});
yield return Check("proc.cached", "Cached analysis skips the measuring pass and gives the same corrections", async context =>
{
var source = Synthetic(30, o => o with { FlickerEv = 0.2 });
var project = Plain with { Exposure = new ExposureSettings { Deflicker = Manual(true) } };
var measured = await RenderPreparation.PrepareAsync(Input(source, project), cancellationToken: context.Cancellation).ConfigureAwait(false);
var decodes = source.Decodes;
var cached = await RenderPreparation.PrepareAsync(Input(source, project) with { Analysis = new PrecomputedAnalysis { LogLuminance = measured.MeasuredLogLuminance } },
cancellationToken: context.Cancellation).ConfigureAwait(false);
Require(cached.Report.MeasuredFrames == 0 && source.Decodes == decodes && cached.ExposureEv.AsSpan().SequenceEqual(measured.ExposureEv), "the cache was not used as is");
return Invariant($"{measured.Report.MeasuredFrames} frames measured once");
});
}
private static IEnumerable<SelfTestCheck> RobustnessChecks()
{
yield return Check("robust.deterministic", "Identical inputs give byte-identical lossless outputs", async context =>
{
var project = Plain with
{
Exposure = new ExposureSettings { Deflicker = Manual(true) },
Timing = new TimingSettings { Mode = Manual(TimingMode.Interpolated), FrameRate = Manual("15") },
};
var a = await Pipeline(context).RenderAsync(Input(Synthetic(12, o => o with { FlickerEv = 0.2 }), project), Target(context, Preset("png-sequence"), "a"), cancellationToken: context.Cancellation)
.ConfigureAwait(false);
var b = await Pipeline(context).RenderAsync(Input(Synthetic(12, o => o with { FlickerEv = 0.2 }), project), Target(context, Preset("png-sequence"), "b"), cancellationToken: context.Cancellation)
.ConfigureAwait(false);
var filesA = Directory.GetFiles(a.OutputPath).Order(StringComparer.Ordinal).ToArray();
var filesB = Directory.GetFiles(b.OutputPath).Order(StringComparer.Ordinal).ToArray();
Require(filesA.Length == filesB.Length && filesA.Length > 12, "different frame counts");
for (var i = 0; i < filesA.Length; i++) Require(File.ReadAllBytes(filesA[i]).AsSpan().SequenceEqual(File.ReadAllBytes(filesB[i])), $"frame {i + 1} differs");
return Invariant($"{filesA.Length} frames identical");
});
foreach (var preset in new[] { "mjpeg-avi", "png-sequence", "gif-preview", "apng" })
{
yield return Check("robust.cancel." + preset.Split('-')[0], $"Cancelling a {preset} render leaves no file behind (§20.4)", async context =>
{
using var cts = CancellationTokenSource.CreateLinkedTokenSource(context.Cancellation);
var progress = new Sink<RenderProgress>(p =>
{
if (p.Stage == RenderStage.Rendering && p.Done == 5) cts.Cancel();
});
try
{
await Pipeline(context).RenderAsync(Input(Synthetic(24)), Target(context, Preset(preset)), progress: progress, cancellationToken: cts.Token).ConfigureAwait(false);
Require(false, "the render was not cancelled");
}
catch (OperationCanceledException) when (!context.Cancellation.IsCancellationRequested)
{
}
Require(Directory.GetFileSystemEntries(context.WorkDirectory).Length == 0, "partial output or temporary files remain");
return "nothing left";
});
}
yield return Check("robust.source-failure", "A failing frame stops the render once, without output", async context =>
{
var input = Input(Synthetic(12)) with { Source = new FailingSource(Synthetic(12), 7) };
var error = await CaptureAsync(() => Pipeline(context).RenderAsync(input, Target(context, Preset("mjpeg-avi")), cancellationToken: context.Cancellation)).ConfigureAwait(false);
Require(error is IOException { Message: "frame 7 is unreadable" }, "unexpected error " + error?.GetType().Name);
Require(Directory.GetFileSystemEntries(context.WorkDirectory).Length == 0, "partial output remains");
return "IOException, no output";
});
yield return Check("robust.encoder-failure", "An encoder failure stops the render once, without output", async context =>
{
var pipeline = new RenderPipeline([new FaultInjectingProvider(new ManagedEncoderProvider(), 4)]);
var error = await CaptureAsync(() => pipeline.RenderAsync(Input(Synthetic(12)), Target(context, Preset("png-sequence")), cancellationToken: context.Cancellation)).ConfigureAwait(false);
Require(error is InvalidDataException { Message: FaultInjectingProvider.Message }, "unexpected error " + error?.GetType().Name);
Require(Directory.GetFileSystemEntries(context.WorkDirectory).Length == 0, "partial output remains");
return "InvalidDataException, no output";
});
yield return Check("robust.unobserved", "Failed renders leave no unobserved task exceptions (§20.4)", async context =>
{
var unobserved = 0;
void Handler(object? sender, UnobservedTaskExceptionEventArgs e) => Interlocked.Increment(ref unobserved);
TaskScheduler.UnobservedTaskException += Handler;
try
{
for (var i = 0; i < 3; i++)
{
var pipeline = new RenderPipeline([new FaultInjectingProvider(new ManagedEncoderProvider(), 2 + i)]);
await CaptureAsync(() => pipeline.RenderAsync(Input(Synthetic(12)), Target(context, Preset("gif-preview")), cancellationToken: context.Cancellation)).ConfigureAwait(false);
var input = Input(Synthetic(12)) with { Source = new FailingSource(Synthetic(12), 3 + i) };
await CaptureAsync(() => Pipeline(context).RenderAsync(input, Target(context, Preset("png-sequence")), cancellationToken: context.Cancellation)).ConfigureAwait(false);
}
GC.Collect();
GC.WaitForPendingFinalizers();
GC.Collect();
}
finally
{
TaskScheduler.UnobservedTaskException -= Handler;
}
Require(unobserved == 0, Invariant($"{unobserved} unobserved exceptions"));
return "none";
});
yield return Check("robust.memory", "Peak memory does not depend on the sequence length (§20.4)", async context =>
{
async Task<long> PeakAsync(int frames, string name)
{
long peak = 0;
var progress = new Sink<RenderProgress>(p =>
{
if (p.Stage == RenderStage.Rendering && p.Done % 8 == 0) peak = long.Max(peak, GC.GetTotalMemory(forceFullCollection: true));
});
var project = Plain with { Exposure = new ExposureSettings { Deflicker = Manual(true) } };
await Pipeline(context).RenderAsync(Input(Synthetic(frames), project), Target(context, Preset("mjpeg-avi"), name), progress: progress,
cancellationToken: context.Cancellation).ConfigureAwait(false);
return peak;
}
await PeakAsync(16, "warm-up").ConfigureAwait(false);
var small = await PeakAsync(48, "short").ConfigureAwait(false);
var large = await PeakAsync(192, "long").ConfigureAwait(false);
Require(large - small < 2 << 20, Invariant($"live heap grew by {(large - small) / 1024} KiB from 48 to 192 frames"));
return Invariant($"48 frames {small / 1024} KiB, 192 frames {large / 1024} KiB");
});
yield return Check("robust.batch", "A batch renders every target and reports the ones that cannot run", async context =>
{
var server = new RenderPipeline([new ManagedEncoderProvider()], EncoderHost.Server);
var results = await server.RenderBatchAsync(Input(Synthetic(12)),
[Target(context, Preset("png-sequence"), "png"), Target(context, Preset("1080p-h264"), "h264"), Target(context, Preset("apng"), "apng")],
cancellationToken: context.Cancellation).ConfigureAwait(false);
Require(results.Count == 3 && results[0].Succeeded && results[2].Succeeded, "a renderable target failed");
Require(results[1].Error is RenderException { ReasonKey: EncoderNotices.NeedsRenderNode }, "the MP4 target was not reported as needing a render node");
return "2 rendered, 1 needs a render node";
});
yield return Check("robust.progress", "Progress counts frames, estimates the end and delivers previews", async context =>
{
var reports = new List<RenderProgress>();
var options = new RenderOptions { PreviewInterval = 4, PreviewLongEdge = 48 };
await Pipeline(context).RenderAsync(Input(Synthetic(12)), Target(context, Preset("jpeg-sequence")), options, new Sink<RenderProgress>(reports.Add), context.Cancellation)
.ConfigureAwait(false);
var rendering = reports.Where(r => r.Stage == RenderStage.Rendering).ToList();
var previews = rendering.Where(r => r.Preview is not null).ToList();
var ok = rendering.Select(r => r.Done).SequenceEqual(Enumerable.Range(1, 12)) && rendering.All(r => r.Remaining >= TimeSpan.Zero)
&& previews.Count == 3 && previews.All(r => r.Preview!.Width == 48) && reports[^1].Stage == RenderStage.Finishing;
foreach (var r in previews) r.Preview!.Dispose();
Require(ok, Invariant($"{rendering.Count} reports, {previews.Count} previews"));
return Invariant($"{rendering.Count} reports, {previews.Count} previews");
});
yield return Check("robust.excluded", "Excluding every frame is reported, not rendered", async context =>
{
var project = Plain with { ExcludedFrames = [.. Enumerable.Range(0, 6)] };
var error = await CaptureAsync(() => Pipeline(context).RenderAsync(Input(Synthetic(6), project), Target(context, Preset("png-sequence")), cancellationToken: context.Cancellation))
.ConfigureAwait(false);
Require(error is RenderException { ReasonKey: "Export.Render.NoFrames" } && Directory.GetFileSystemEntries(context.WorkDirectory).Length == 0, "no NoFrames error");
return "Export.Render.NoFrames";
});
}
/// <summary>The exception <paramref name="render"/> throws, or null.</summary>
private static async Task<Exception?> CaptureAsync(Func<Task> render)
{
try
{
await render().ConfigureAwait(false);
return null;
}
catch (Exception ex) when (ex is not OperationCanceledException)
{
return ex;
}
}
/// <summary>Throws an <see cref="IOException"/> for one frame, as an unreadable file would.</summary>
private sealed class FailingSource(IRenderFrameSource inner, int failAt) : IRenderFrameSource
{
public int FrameCount => inner.FrameCount;
public int Width => inner.Width;
public int Height => inner.Height;
public ValueTask<ImageBuffer> GetFrameAsync(int index, int maxLongEdge, DecodePurpose purpose, CancellationToken cancellationToken) =>
index == failAt ? throw new IOException($"frame {index} is unreadable") : inner.GetFrameAsync(index, maxLongEdge, purpose, cancellationToken);
}
/// <summary>Adds a bright square to one frame (a passing aircraft light).</summary>
private sealed class TransientSource(IRenderFrameSource inner, int frame) : IRenderFrameSource
{
public int FrameCount => inner.FrameCount;
public int Width => inner.Width;
public int Height => inner.Height;
public async ValueTask<ImageBuffer> GetFrameAsync(int index, int maxLongEdge, DecodePurpose purpose, CancellationToken cancellationToken)
{
var image = await inner.GetFrameAsync(index, maxLongEdge, purpose, cancellationToken).ConfigureAwait(false);
if (index != frame) return image;
for (var c = 0; c < image.Channels; c++)
{
for (var y = image.Height / 3; y < image.Height / 3 + 10; y++)
{
for (var x = image.Width / 2; x < image.Width / 2 + 10; x++) image[c, x, y] = 1;
}
}
return image;
}
}
/// <summary>Wraps a real provider and fails its sessions at a given frame (fault injection).</summary>
private sealed class FaultInjectingProvider(IVideoEncoderProvider inner, int failAt) : IVideoEncoderProvider
{
public const string Message = "injected encoder fault";
public string Name => inner.Name;
public IReadOnlyList<EncoderCapability> Capabilities => inner.Capabilities;
public bool CanEncode(EncodeSettings settings) => inner.CanEncode(settings);
public IVideoEncoderSession Open(EncodeSettings settings) => new Session(inner.Open(settings), failAt);
private sealed class Session(IVideoEncoderSession inner, int failAt) : IVideoEncoderSession
{
private int _frames;
public string EncoderName => inner.EncoderName;
public bool IsHardware => inner.IsHardware;
public void WriteFrame(ImageBuffer frame, long duration90k)
{
if (_frames++ == failAt) throw new InvalidDataException(Message);
inner.WriteFrame(frame, duration90k);
}
public void Complete() => inner.Complete();
public void Dispose() => inner.Dispose();
}
}
}
@@ -0,0 +1,83 @@
using Titano.Core.Diagnostics.Synthetic;
using Titano.Core.Imaging;
using Titano.Core.Imaging.Geometry;
namespace Titano.Core.Render.Diagnostics;
/// <summary>
/// <see cref="IRenderFrameSource"/> over a <see cref="SyntheticSequence"/> (self-test and tests). An optional camera
/// motion translates each frame's content by a per-frame offset in pixels (pans, shake). Frames are rendered on demand,
/// so memory does not depend on the sequence length.
/// </summary>
public sealed class SyntheticFrameSource(SyntheticSequence sequence, Func<int, (double X, double Y)>? cameraMotion = null) : IRenderFrameSource
{
private int _decodes;
private int _largestRequest;
public SyntheticSequence Sequence { get; } = sequence ?? throw new ArgumentNullException(nameof(sequence));
public int FrameCount => Sequence.Count;
public int Width => Sequence.Options.Width;
public int Height => Sequence.Options.Height;
/// <summary>Frames produced so far.</summary>
public int Decodes => Volatile.Read(ref _decodes);
/// <summary>Largest long edge requested for rendering (0 = full size).</summary>
public int LargestRenderRequest => Volatile.Read(ref _largestRequest);
/// <summary>Capture metadata of the sequence's frames.</summary>
public SourceFrameInfo[] Metadata() => SourceFrameInfo.From(Sequence.Frames);
public ValueTask<ImageBuffer> GetFrameAsync(int index, int maxLongEdge, DecodePurpose purpose, CancellationToken cancellationToken)
{
cancellationToken.ThrowIfCancellationRequested();
Interlocked.Increment(ref _decodes);
if (purpose == DecodePurpose.Render) InterlockedMax(ref _largestRequest, maxLongEdge);
var frame = Sequence.Render(index);
try
{
if (cameraMotion is not null)
{
var (dx, dy) = cameraMotion(index);
var moved = new ImageBuffer(frame.Width, frame.Height, frame.Channels, clear: false);
try
{
GeometryStage.Warp(frame, moved, Affine2D.Translation(-dx, -dy), BorderMode.Clamp, cancellationToken);
}
catch
{
moved.Dispose();
throw;
}
frame.Dispose();
frame = moved;
}
if (maxLongEdge > 0 && int.Max(frame.Width, frame.Height) > maxLongEdge)
{
var small = Resampler.Thumbnail(frame, maxLongEdge);
frame.Dispose();
frame = small;
}
return ValueTask.FromResult(frame);
}
catch
{
frame.Dispose();
throw;
}
}
private static void InterlockedMax(ref int target, int value)
{
var current = Volatile.Read(ref target);
while (value > current)
{
var seen = Interlocked.CompareExchange(ref target, value, current);
if (seen == current) return;
current = seen;
}
}
}
+95
View File
@@ -0,0 +1,95 @@
using Titano.Core.Imaging;
using Titano.Core.Motion;
namespace Titano.Core.Render;
/// <summary>Least-recently-used cache of prepared (corrected and warped) frames by source index; owns its buffers.</summary>
internal sealed class PreparedFrameCache(int capacity) : IDisposable
{
private readonly List<(int Index, ImageBuffer Frame)> _entries = new(capacity + 1);
public bool TryGet(int index, out ImageBuffer frame)
{
for (var i = 0; i < _entries.Count; i++)
{
if (_entries[i].Index != index) continue;
var entry = _entries[i];
_entries.RemoveAt(i);
_entries.Add(entry);
frame = entry.Frame;
return true;
}
frame = null!;
return false;
}
public void Add(int index, ImageBuffer frame)
{
_entries.Add((index, frame));
while (_entries.Count > capacity)
{
_entries[0].Frame.Dispose();
_entries.RemoveAt(0);
}
}
public void Dispose()
{
foreach (var (_, frame) in _entries) frame.Dispose();
_entries.Clear();
}
}
/// <summary>Flow fields between two source frames (forward, and backward when synthesis needed it).</summary>
internal sealed record FlowPair(MotionField Forward, MotionField? Backward);
/// <summary>Least-recently-used cache of flow fields by source pair; owns its fields.</summary>
internal sealed class FlowCache(int capacity) : IDisposable
{
private readonly List<(int From, int To, FlowPair Flows)> _entries = new(capacity + 1);
public bool TryGet(int from, int to, bool needBackward, out FlowPair flows)
{
for (var i = 0; i < _entries.Count; i++)
{
var entry = _entries[i];
if (entry.From != from || entry.To != to) continue;
if (needBackward && entry.Flows.Backward is null) break;
_entries.RemoveAt(i);
_entries.Add(entry);
flows = entry.Flows;
return true;
}
flows = null!;
return false;
}
/// <summary>Adds (or replaces) the flows of a pair.</summary>
public void Add(int from, int to, FlowPair flows)
{
var existing = _entries.FindIndex(e => e.From == from && e.To == to);
if (existing >= 0)
{
Release(_entries[existing].Flows);
_entries.RemoveAt(existing);
}
_entries.Add((from, to, flows));
while (_entries.Count > capacity)
{
Release(_entries[0].Flows);
_entries.RemoveAt(0);
}
}
public void Dispose()
{
foreach (var entry in _entries) Release(entry.Flows);
_entries.Clear();
}
private static void Release(FlowPair flows)
{
flows.Forward.Dispose();
flows.Backward?.Dispose();
}
}
@@ -0,0 +1,47 @@
using Titano.Core.Imaging;
using Titano.Core.Model;
namespace Titano.Core.Render;
/// <summary>
/// Decoded source frames of a render by index. The application backs it with the image decoders and the sliding
/// <c>FrameWindow</c> (read-ahead, disk spill); tests and the self-test use synthetic sources. Sequential index order is
/// the common access pattern; neighbours may be requested again for flow and interpolation.
/// </summary>
public interface IRenderFrameSource
{
int FrameCount { get; }
/// <summary>Full-resolution width after orientation.</summary>
int Width { get; }
/// <summary>Full-resolution height after orientation.</summary>
int Height { get; }
/// <summary>
/// Frame <paramref name="index"/> in linear light, its long edge at most <paramref name="maxLongEdge"/> (0 = full size).
/// A source may return a smaller frame of the same aspect (e.g. an embedded preview). The caller owns the buffer.
/// </summary>
ValueTask<ImageBuffer> GetFrameAsync(int index, int maxLongEdge, DecodePurpose purpose, CancellationToken cancellationToken);
}
/// <summary>Capture metadata of one source frame used by the plan and the preparation.</summary>
/// <param name="CapturedAt">Camera clock (clock-corrected when available); null when unknown.</param>
/// <param name="ExposureTime">Shutter time in seconds (real shutter angle for motion blur).</param>
/// <param name="ExposureValue">EV at ISO 100 (holy-grail steps).</param>
public readonly record struct SourceFrameInfo(DateTime? CapturedAt, double? ExposureTime, double? ExposureValue)
{
/// <summary>Metadata of archived frames, optionally with clock-corrected times (<c>LightAnalysisReport.AdjustedTimes</c>).</summary>
public static SourceFrameInfo[] From(IReadOnlyList<Frame> frames, IReadOnlyList<DateTime?>? adjustedTimes = null)
{
ArgumentNullException.ThrowIfNull(frames);
if (adjustedTimes is not null && adjustedTimes.Count != frames.Count) throw new ArgumentException("One time per frame is required.", nameof(adjustedTimes));
var result = new SourceFrameInfo[frames.Count];
for (var i = 0; i < frames.Count; i++)
{
var f = frames[i];
result[i] = new SourceFrameInfo(adjustedTimes is null ? f.CapturedAt : adjustedTimes[i], f.ExposureTime, f.ExposureValue);
}
return result;
}
}
+17
View File
@@ -0,0 +1,17 @@
using Titano.Core.Project;
namespace Titano.Core.Render;
/// <summary>
/// Reads value-type <see cref="Auto{T}"/> settings. For value types <see cref="Auto{T}.AutoValue"/> is never null (an
/// unconstrained <c>T?</c> is <c>T</c>), so <see cref="Auto{T}.Resolve"/> returns <c>default</c> instead of the fallback
/// when there is no advice; here a default automatic value means "no advice" and yields the fallback.
/// </summary>
internal static class ProjectValues
{
public static T Get<T>(Auto<T> setting, T fallback) where T : struct
{
if (!setting.IsAuto) return setting.Manual;
return EqualityComparer<T>.Default.Equals(setting.AutoValue, default) ? fallback : setting.AutoValue;
}
}
+206
View File
@@ -0,0 +1,206 @@
using System.Globalization;
using Titano.Core.Export;
using Titano.Core.Imaging.Geometry;
using Titano.Core.Motion;
using Titano.Core.Project;
using Titano.Core.Video;
namespace Titano.Core.Render;
/// <summary>
/// Output size, decode size and per-frame warp of a render. <see cref="CameraSettings.Crop"/> is a normalised
/// [x, y, width, height] rectangle of the camera view; the output aspect is the export's when it fixes both dimensions,
/// otherwise the camera aspect (source = frame aspect). Virtual-camera keyframes are keyed to source frame positions, so
/// they stay attached to the content when timing, frame rate or fitting change. The stabiliser correction, the camera
/// pose (zoomed by the stabilisation zoom) and the crop become one output→source map, resampled once.
/// </summary>
public sealed class RenderGeometry
{
private static readonly CameraState Neutral = new(0.5, 0.5, 1, 0);
private readonly VirtualCamera? _camera;
private readonly RectD _crop;
private readonly double _offsetX;
private readonly double _offsetY;
private readonly double _stabilizationZoom;
private readonly double _fittedWidth;
private readonly double _fittedHeight;
private readonly double _maxZoom;
private readonly int _maxWorkingLongEdge;
private RenderGeometry(VirtualCamera? camera, RectD crop, double offsetX, double offsetY, double stabilizationZoom, int sourceWidth, int sourceHeight,
int outputWidth, int outputHeight, double fittedWidth, double fittedHeight, double maxZoom, int maxWorkingLongEdge, IReadOnlyList<RenderWarning> warnings)
{
_camera = camera;
_crop = crop;
_offsetX = offsetX;
_offsetY = offsetY;
_stabilizationZoom = stabilizationZoom;
SourceWidth = sourceWidth;
SourceHeight = sourceHeight;
OutputWidth = outputWidth;
OutputHeight = outputHeight;
_fittedWidth = fittedWidth;
_fittedHeight = fittedHeight;
_maxZoom = maxZoom;
_maxWorkingLongEdge = maxWorkingLongEdge;
Warnings = warnings;
}
public int SourceWidth { get; }
public int SourceHeight { get; }
public int OutputWidth { get; }
public int OutputHeight { get; }
/// <summary>Remarks about ignored camera values.</summary>
public IReadOnlyList<RenderWarning> Warnings { get; }
/// <summary>
/// Long edge to decode source frames at: enough that the most zoomed-in view still has one source pixel per output
/// pixel, never more than the source, capped by <see cref="RenderOptions.MaxWorkingLongEdge"/>.
/// </summary>
public int WorkingLongEdge
{
get
{
var needed = double.Max(OutputWidth / _fittedWidth, OutputHeight / _fittedHeight) * _maxZoom;
var edge = (int)double.Ceiling(int.Max(SourceWidth, SourceHeight) * double.Min(1, needed));
edge = int.Clamp(edge, int.Min(16, int.Max(SourceWidth, SourceHeight)), int.Max(SourceWidth, SourceHeight));
return _maxWorkingLongEdge > 0 ? int.Min(edge, _maxWorkingLongEdge) : edge;
}
}
/// <summary>Plans the geometry of <paramref name="export"/> for a source of the given full-resolution size.</summary>
/// <param name="stabilizationZoom">Zoom that hides stabilisation borders (<see cref="RenderCorrections.StabilizationZoom"/>).</param>
/// <param name="maxWorkingLongEdge">Decode-size cap (0 = none); it also caps source-sized outputs.</param>
public static RenderGeometry Create(CameraSettings camera, ResolvedExport export, int sourceWidth, int sourceHeight, double stabilizationZoom = 1, int maxWorkingLongEdge = 0)
{
ArgumentNullException.ThrowIfNull(camera);
ArgumentNullException.ThrowIfNull(export);
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(sourceWidth);
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(sourceHeight);
var warnings = new List<RenderWarning>();
var crop = NormalisedCrop(camera.Crop, warnings);
if (!AspectRatio.TryParse(camera.Aspect.Resolve("source"), out var aspect))
{
warnings.Add(new RenderWarning("Export.Render.AspectIgnored", camera.Aspect.Resolve(string.Empty)));
aspect = AspectRatio.Source;
}
var fixedSize = export.Width > 0 && export.Height > 0;
var ratio = fixedSize ? export.Width / (double)export.Height : aspect.Resolve(sourceWidth, sourceHeight);
if (fixedSize && !aspect.IsSource && double.Abs(aspect.Resolve(sourceWidth, sourceHeight) / ratio - 1) > 0.01)
warnings.Add(new RenderWarning("Export.Render.AspectFromPreset", aspect.ToString(), string.Create(CultureInfo.InvariantCulture, $"{export.Width}:{export.Height}")));
var cropPixels = new RectD(crop.X * sourceWidth, crop.Y * sourceHeight, crop.Width * sourceWidth, crop.Height * sourceHeight);
var fitted = AspectRatio.FitCrop(cropPixels, ratio, camera.OffsetX, camera.OffsetY);
int width, height;
if (fixedSize) (width, height) = (export.Width, export.Height);
else if (export.Width > 0) (width, height) = (export.Width, (int)double.Round(export.Width / ratio));
else if (export.Height > 0) (width, height) = ((int)double.Round(export.Height * ratio), export.Height);
else
{
var scale = maxWorkingLongEdge > 0 ? double.Min(1, maxWorkingLongEdge / double.Max(fitted.Width, fitted.Height)) : 1;
(width, height) = ((int)double.Round(fitted.Width * scale), (int)double.Round(fitted.Height * scale));
}
if (!VideoCodecInfo.IsManaged(export.Codec))
{
width &= ~1;
height &= ~1;
}
width = int.Max(VideoCodecInfo.IsManaged(export.Codec) ? 1 : 2, width);
height = int.Max(VideoCodecInfo.IsManaged(export.Codec) ? 1 : 2, height);
var cameraPath = Camera(camera.Keyframes, warnings);
var maxZoom = (cameraPath?.Keyframes.Max(k => k.Zoom) ?? 1) * stabilizationZoom;
return new RenderGeometry(cameraPath, crop, camera.OffsetX, camera.OffsetY, stabilizationZoom, sourceWidth, sourceHeight, width, height,
fitted.Width, fitted.Height, maxZoom, maxWorkingLongEdge, warnings);
}
/// <summary>The same geometry rendering into a different output size (e.g. capped by the encoder).</summary>
public RenderGeometry WithOutputSize(int width, int height) => width == OutputWidth && height == OutputHeight
? this
: new RenderGeometry(_camera, _crop, _offsetX, _offsetY, _stabilizationZoom, SourceWidth, SourceHeight, width, height, _fittedWidth, _fittedHeight,
_maxZoom, _maxWorkingLongEdge, Warnings);
/// <summary>Camera pose at a (fractional) source position, including the stabilisation zoom.</summary>
public CameraState PoseAt(double sourcePosition)
{
var pose = _camera?.Evaluate(sourcePosition) ?? Neutral;
return pose with { Zoom = pose.Zoom * _stabilizationZoom };
}
/// <summary>Geometry of one decoded frame of <paramref name="frameWidth"/>×<paramref name="frameHeight"/> pixels.</summary>
/// <param name="stabilization">The frame's stabiliser correction at this frame size (source → stabilised).</param>
public GeometrySettings For(int frameWidth, int frameHeight, double sourcePosition, Affine2D stabilization)
{
var view = VirtualCamera.ViewToSource(PoseAt(sourcePosition), frameWidth, frameHeight);
return new GeometrySettings
{
Crop = new RectD(_crop.X * frameWidth, _crop.Y * frameHeight, _crop.Width * frameWidth, _crop.Height * frameHeight),
Aspect = AspectRatio.Source,
OffsetX = _offsetX,
OffsetY = _offsetY,
OutputWidth = OutputWidth,
OutputHeight = OutputHeight,
Warp = stabilization.IsIdentity() ? view : stabilization.Invert() * view,
Border = BorderMode.Clamp,
};
}
private static RectD NormalisedCrop(double[]? crop, List<RenderWarning> warnings)
{
var full = new RectD(0, 0, 1, 1);
if (crop is null) return full;
if (crop.Length != 4 || !crop.All(double.IsFinite))
{
warnings.Add(new RenderWarning("Export.Render.CropIgnored"));
return full;
}
var x = double.Clamp(crop[0], 0, 1);
var y = double.Clamp(crop[1], 0, 1);
var w = double.Min(crop[2], 1 - x);
var h = double.Min(crop[3], 1 - y);
if (w <= 1e-3 || h <= 1e-3)
{
warnings.Add(new RenderWarning("Export.Render.CropIgnored"));
return full;
}
return new RectD(x, y, w, h);
}
private static VirtualCamera? Camera(IReadOnlyList<CameraKey> keys, List<RenderWarning> warnings)
{
if (keys.Count == 0) return null;
var frames = new Dictionary<int, CameraKeyframe>();
foreach (var k in keys)
{
if (!double.IsFinite(k.CenterX + k.CenterY + k.Zoom + k.Rotation))
{
warnings.Add(new RenderWarning("Export.Render.KeyframeIgnored", k.Frame.ToString(CultureInfo.InvariantCulture)));
continue;
}
frames[k.Frame] = new CameraKeyframe(k.Frame, k.CenterX, k.CenterY, double.Max(1, k.Zoom), k.Rotation) { Easing = Easing(k.Easing, warnings) };
}
return frames.Count == 0 ? null : new VirtualCamera(frames.Values);
}
/// <summary>"Linear", "EaseIn", "EaseOut", "EaseInOut" or "x1,y1,x2,y2" control points (CSS cubic-bezier).</summary>
private static BezierEasing Easing(string? text, List<RenderWarning> warnings)
{
switch (text?.Trim().ToLowerInvariant())
{
case null or "" or "easeinout": return BezierEasing.EaseInOut;
case "linear": return BezierEasing.Linear;
case "easein": return BezierEasing.EaseIn;
case "easeout": return BezierEasing.EaseOut;
}
var parts = text.Split(',');
if (parts.Length == 4
&& double.TryParse(parts[0], NumberStyles.Float, CultureInfo.InvariantCulture, out var x1) && x1 is >= 0 and <= 1
&& double.TryParse(parts[1], NumberStyles.Float, CultureInfo.InvariantCulture, out var y1) && double.IsFinite(y1)
&& double.TryParse(parts[2], NumberStyles.Float, CultureInfo.InvariantCulture, out var x2) && x2 is >= 0 and <= 1
&& double.TryParse(parts[3], NumberStyles.Float, CultureInfo.InvariantCulture, out var y2) && double.IsFinite(y2))
return new BezierEasing(x1, y1, x2, y2);
warnings.Add(new RenderWarning("Export.Render.EasingIgnored", text));
return BezierEasing.EaseInOut;
}
}
+127
View File
@@ -0,0 +1,127 @@
using Titano.Core.Analysis;
using Titano.Core.Export;
using Titano.Core.Imaging;
using Titano.Core.Motion;
using Titano.Core.Project;
namespace Titano.Core.Render;
/// <summary>Everything a render of one sequence reads, shared by every preset of a batch.</summary>
public sealed record RenderInput
{
public required IRenderFrameSource Source { get; init; }
/// <summary>Capture metadata, one entry per source frame.</summary>
public required IReadOnlyList<SourceFrameInfo> Frames { get; init; }
public required ProjectSettings Project { get; init; }
/// <summary>Cached deep-analysis results; missing parts are measured by the preparation pass.</summary>
public PrecomputedAnalysis? Analysis { get; init; }
}
/// <summary>One output of a render: the resolved export values and where the file (or sequence folder) goes.</summary>
/// <param name="OutputPath">Full path of the file, or of the folder for image sequences (see <see cref="ExportNaming.OutputPath"/>).</param>
public sealed record RenderTarget(ResolvedExport Export, string OutputPath);
/// <summary>Tuning of a render that is not part of the project.</summary>
public sealed record RenderOptions
{
public static RenderOptions Default { get; } = new();
/// <summary>Long edge of the frames measured by the preparation pass.</summary>
public int AnalysisLongEdge { get; init; } = 512;
/// <summary>Upper bound of the decode size (0 = as large as the output geometry needs); previews set a small value.</summary>
public int MaxWorkingLongEdge { get; init; }
/// <summary>A downscaled copy of every n-th rendered frame is reported for the live preview (0 = never).</summary>
public int PreviewInterval { get; init; }
public int PreviewLongEdge { get; init; } = 640;
/// <summary>Prepared (exposure-corrected, warped) frames kept for flow and interpolation neighbours (at least 3).</summary>
public int CacheFrames { get; init; } = 4;
public RenderPlanOptions Plan { get; init; } = RenderPlanOptions.Default;
}
public enum RenderStage
{
/// <summary>Measuring the sequence (luminance, colour, camera path).</summary>
Preparing,
/// <summary>Rendering and encoding output frames.</summary>
Rendering,
/// <summary>Flushing and committing the output.</summary>
Finishing,
}
/// <summary>Progress of a render. <see cref="Preview"/> (when present) belongs to the receiver, which disposes it.</summary>
/// <param name="Done">Frames measured (Preparing) or output frames rendered (Rendering).</param>
/// <param name="Total">Frames of the current stage.</param>
/// <param name="FramesPerSecond">Recent throughput of the current stage.</param>
/// <param name="Remaining">Estimated time to the end of the stage; null until measurable.</param>
public sealed record RenderProgress(RenderStage Stage, int Done, int Total, double FramesPerSecond, TimeSpan Elapsed, TimeSpan? Remaining, ImageBuffer? Preview = null)
{
public double Fraction => Total > 0 ? (double)Done / Total : 0;
}
/// <summary>
/// Results of the advisor's deep analysis reused by the preparation (all arrays have one entry per source frame).
/// Invalid or mismatched parts are ignored and measured again.
/// </summary>
public sealed record PrecomputedAnalysis
{
/// <summary>Trimmed-mean log2 luminance (NaN = unusable frame).</summary>
public double[]? LogLuminance { get; init; }
/// <summary>Mean linear red, green and blue (white-balance smoothing).</summary>
public double[]? MeanRed { get; init; }
public double[]? MeanGreen { get; init; }
public double[]? MeanBlue { get; init; }
/// <summary>Sky/land mask with the region series measured through it.</summary>
public RegionMask? Regions { get; init; }
public double[]? SkyLogLuminance { get; init; }
public double[]? LandLogLuminance { get; init; }
/// <summary>Stabilisation solved over the sequence, one correction per source frame, in pixels of a frame of
/// <see cref="StabilizationWidth"/>×<see cref="StabilizationHeight"/>.</summary>
public StabilizationResult? Stabilization { get; init; }
public int StabilizationWidth { get; init; }
public int StabilizationHeight { get; init; }
/// <summary>Path smoothing σ the stabilisation was solved with; a different project value triggers a new solve.</summary>
public double StabilizationSmoothing { get; init; }
}
/// <summary>A localisable remark about a render (key plus invariant-culture arguments).</summary>
public sealed record RenderWarning(string Key, IReadOnlyList<string> Args)
{
public RenderWarning(string key, params string[] args) : this(key, (IReadOnlyList<string>)args)
{
}
public override string ToString() => Args.Count == 0 ? Key : $"{Key}({string.Join(", ", Args)})";
}
/// <summary>A render that cannot start or continue for a reason the user can act on.</summary>
public sealed class RenderException : Exception
{
public RenderException(string reasonKey, string message, IReadOnlyList<string>? args = null, Exception? innerException = null)
: base(message, innerException)
{
ReasonKey = reasonKey;
Args = args ?? [];
}
/// <summary>Localisation key of the reason (e.g. <see cref="EncoderNotices.NeedsRenderNode"/>).</summary>
public string ReasonKey { get; }
public IReadOnlyList<string> Args { get; }
}
+461
View File
@@ -0,0 +1,461 @@
using System.Diagnostics;
using System.Globalization;
using Titano.Core.Analysis;
using Titano.Core.Diagnostics;
using Titano.Core.Export;
using Titano.Core.Imaging;
using Titano.Core.Imaging.Geometry;
using Titano.Core.Motion;
using Titano.Core.Project;
using Titano.Core.Video;
namespace Titano.Core.Render;
/// <summary>
/// Renders sequences (BRIEF §11). For every planned output frame: source frames come from the
/// <see cref="IRenderFrameSource"/> at the working size; per-frame exposure corrections (deflicker, holy grail, white
/// balance, regions) are applied; stabilisation, virtual camera and crop are resampled once to the output size;
/// fractional positions are synthesised from the bidirectional flow; motion blur follows the flow with shutter-angle
/// composition; stacking (median, mean, star trails) and the highlight knee come last, then the encoder. Encoding of a
/// frame overlaps the processing of the next. Cancellation and failures leave no output behind (sessions delete their
/// partial files on dispose) and every background task is awaited, so exceptions surface exactly once.
/// </summary>
public sealed class RenderPipeline(IReadOnlyList<IVideoEncoderProvider> encoders, EncoderHost host = EncoderHost.Client)
{
internal const string LogCategory = "Render";
/// <summary>Encoder providers in priority order (client: Media Foundation, then managed; server: managed).</summary>
public IReadOnlyList<IVideoEncoderProvider> Encoders { get; } = encoders ?? throw new ArgumentNullException(nameof(encoders));
public EncoderHost Host { get; } = host;
/// <summary>Geometry, encoder and plan of a target without rendering (Export tab, estimates).</summary>
public RenderSetup Setup(RenderInput input, RenderTarget target, RenderOptions? options = null, RenderCorrections? corrections = null) =>
RenderSetup.Create(input, target, Encoders, Host, options, corrections);
/// <summary>Prepares the sequence and renders one target.</summary>
public async Task<RenderResult> RenderAsync(RenderInput input, RenderTarget target, RenderOptions? options = null, IProgress<RenderProgress>? progress = null,
CancellationToken cancellationToken = default)
{
var corrections = await RenderPreparation.PrepareAsync(input, options, progress, cancellationToken).ConfigureAwait(false);
return await RenderAsync(input, corrections, target, options, progress, cancellationToken).ConfigureAwait(false);
}
/// <summary>Renders one target with corrections prepared earlier (shared by a batch).</summary>
/// <exception cref="RenderException">No encoder can produce the target, or every frame is excluded.</exception>
public async Task<RenderResult> RenderAsync(RenderInput input, RenderCorrections corrections, RenderTarget target, RenderOptions? options = null,
IProgress<RenderProgress>? progress = null, CancellationToken cancellationToken = default)
{
ArgumentNullException.ThrowIfNull(input);
ArgumentNullException.ThrowIfNull(corrections);
ArgumentNullException.ThrowIfNull(target);
options ??= RenderOptions.Default;
if (corrections.FrameCount != input.Source.FrameCount) throw new ArgumentException("The corrections belong to another sequence.", nameof(corrections));
await Task.CompletedTask.ConfigureAwait(ConfigureAwaitOptions.ForceYielding);
cancellationToken.ThrowIfCancellationRequested();
var setup = Setup(input, target, options, corrections);
if (!setup.Encoder.IsReady)
{
var notice = setup.Encoder.Notices.LastOrDefault() ?? new EncoderNotice(EncoderNotices.NoEncoder, setup.Encoder.Settings.Codec.ToString());
throw new RenderException(notice.Key, $"No encoder can produce {target.Export.Codec} here ({setup.Encoder.Status})", notice.Args);
}
if (setup.Plan.Frames.Count == 0) throw new RenderException("Export.Render.NoFrames", "Every frame is excluded.");
using var run = new RenderRun(input, corrections, setup, options, progress);
return await run.ExecuteAsync(cancellationToken).ConfigureAwait(false);
}
/// <summary>
/// Renders several targets of one sequence one after the other, preparing the sequence once. A failing target is
/// reported and the batch continues; cancellation stops the batch.
/// </summary>
public async Task<IReadOnlyList<BatchItemResult>> RenderBatchAsync(RenderInput input, IReadOnlyList<RenderTarget> targets, RenderOptions? options = null,
IProgress<RenderProgress>? progress = null, CancellationToken cancellationToken = default)
{
ArgumentNullException.ThrowIfNull(targets);
var corrections = await RenderPreparation.PrepareAsync(input, options, progress, cancellationToken).ConfigureAwait(false);
var results = new List<BatchItemResult>(targets.Count);
foreach (var target in targets)
{
cancellationToken.ThrowIfCancellationRequested();
try
{
results.Add(new BatchItemResult(target, await RenderAsync(input, corrections, target, options, progress, cancellationToken).ConfigureAwait(false), null));
}
catch (Exception ex) when (!(ex is OperationCanceledException && cancellationToken.IsCancellationRequested))
{
Log.Warning(LogCategory, $"Batch target {target.OutputPath} failed", ex);
results.Add(new BatchItemResult(target, null, ex));
}
}
return results;
}
}
/// <summary>State of one render: caches, flow, stacking, the encoder session and the encode in flight.</summary>
internal sealed class RenderRun : IDisposable
{
/// <summary>Largest speed (source frames per output period) that scales motion blur; faster plans blur no further.</summary>
private const double MaxBlurSpeed = 4;
private readonly RenderInput _input;
private readonly RenderCorrections _corrections;
private readonly RenderSetup _setup;
private readonly RenderOptions _options;
private readonly IProgress<RenderProgress>? _progress;
private readonly RenderPlan _plan;
private readonly RenderGeometry _geometry;
private readonly PreparedFrameCache _prepared;
private readonly FlowCache _flows = new(2);
private readonly MotionBlurRenderer _blur = new();
private readonly List<RenderWarning> _warnings = [];
private readonly Stopwatch _clock = new();
private readonly int _workingEdge;
private readonly float? _knee;
private readonly double _targetShutter;
private readonly FlowQuality _flowQuality;
private OpticalFlowEngine? _flowEngine;
private RegionMask? _mask;
private IVideoEncoderSession? _session;
private Task? _encoding;
private int _done;
public RenderRun(RenderInput input, RenderCorrections corrections, RenderSetup setup, RenderOptions options, IProgress<RenderProgress>? progress)
{
_input = input;
_corrections = corrections;
_setup = setup;
_options = options;
_progress = progress;
_plan = setup.Plan;
_geometry = setup.Geometry;
_prepared = new PreparedFrameCache(int.Max(3, options.CacheFrames));
_workingEdge = _geometry.WorkingLongEdge;
var exposure = input.Project.Exposure;
if (exposure.HighlightKnee is { } knee)
{
if (knee is > 0 and < 1) _knee = (float)knee;
else _warnings.Add(new RenderWarning("Export.Render.KneeIgnored", knee.ToString(CultureInfo.InvariantCulture)));
}
var motion = input.Project.Motion;
_targetShutter = double.Clamp(ProjectValues.Get(motion.TargetShutterAngle, 180.0), 0, 360);
_flowQuality = ProjectValues.Get(motion.FlowQuality, FlowQualitySetting.Balanced) switch
{
FlowQualitySetting.Draft => FlowQuality.Draft,
FlowQualitySetting.Best => FlowQuality.Best,
_ => FlowQuality.Balanced,
};
}
public async Task<RenderResult> ExecuteAsync(CancellationToken cancellationToken)
{
var settings = _setup.Encoder.Settings;
_clock.Start();
Log.Info(RenderPipeline.LogCategory, $"Rendering {_plan.Frames.Count} frames ({_plan.SlotCount} periods) to {settings.Codec} {settings.Width}×{settings.Height} @ {settings.FrameRate}: {settings.OutputPath}");
var session = _session = _setup.Encoder.Open();
try
{
await RenderFramesAsync(cancellationToken).ConfigureAwait(false);
await FlushEncodingAsync().ConfigureAwait(false);
_progress?.Report(new RenderProgress(RenderStage.Finishing, _done, _plan.Frames.Count, Fps(), _clock.Elapsed, TimeSpan.Zero));
session.Complete();
}
catch
{
await ObserveEncodingAsync().ConfigureAwait(false);
throw;
}
finally
{
session.Dispose();
}
_clock.Stop();
var warnings = new List<RenderWarning>(_setup.Warnings);
warnings.AddRange(_corrections.Report.Warnings);
warnings.AddRange(_warnings);
var result = new RenderResult
{
OutputPath = settings.OutputPath,
PresetId = _setup.Target.Export.PresetId,
Codec = settings.Codec,
Width = settings.Width,
Height = settings.Height,
FrameRate = settings.FrameRate,
DurationSeconds = _plan.DurationSeconds,
FrameCount = _plan.Frames.Count,
Bytes = RenderResult.SizeOf(settings.OutputPath),
EncoderName = session.EncoderName,
Hardware = session.IsHardware,
Elapsed = _clock.Elapsed,
Warnings = warnings,
};
Log.Info(RenderPipeline.LogCategory, $"Rendered {result.FrameCount} frames in {result.Elapsed.TotalSeconds:F1} s with {result.EncoderName}: {result.Bytes} bytes");
return result;
}
public void Dispose()
{
_prepared.Dispose();
_flows.Dispose();
_flowEngine?.Dispose();
}
private async Task RenderFramesAsync(CancellationToken cancellationToken)
{
var stack = _input.Project.Stack;
switch (stack.Mode)
{
case StackSetting.Median or StackSetting.Mean:
await RenderWindowStackAsync(stack, cancellationToken).ConfigureAwait(false);
break;
case StackSetting.StarTrails:
using (var trails = new StarTrailStacker(StarTrailStacker.DecayForTrailLength(stack.Length > 0 ? stack.Length : double.PositiveInfinity)))
{
foreach (var planned in _plan.Frames)
{
cancellationToken.ThrowIfCancellationRequested();
using (var frame = await RenderFrameAsync(planned, blur: false, cancellationToken).ConfigureAwait(false)) trails.Add(frame);
await EmitAsync(trails.Result!.Clone(), planned.Duration90k).ConfigureAwait(false);
}
}
break;
default:
foreach (var planned in _plan.Frames)
{
cancellationToken.ThrowIfCancellationRequested();
var frame = await RenderFrameAsync(planned, _setup.MotionBlur, cancellationToken).ConfigureAwait(false);
await EmitAsync(frame, planned.Duration90k).ConfigureAwait(false);
}
break;
}
}
/// <summary>Centred median/mean window: output k is emitted once frame k + half has been pushed (the tail reuses the
/// last full window).</summary>
private async Task RenderWindowStackAsync(StackSettings stack, CancellationToken cancellationToken)
{
var window = int.Max(1, stack.Length);
var half = (window - 1) / 2;
using var stacker = new TemporalStacker(window, stack.Mode == StackSetting.Median ? StackMode.Median : StackMode.Mean);
var pending = new Queue<PlannedFrame>();
foreach (var planned in _plan.Frames)
{
cancellationToken.ThrowIfCancellationRequested();
using (var frame = await RenderFrameAsync(planned, blur: false, cancellationToken).ConfigureAwait(false)) stacker.Push(frame);
pending.Enqueue(planned);
if (pending.Count > half) await EmitStackAsync(stacker, pending.Dequeue(), cancellationToken).ConfigureAwait(false);
}
while (pending.Count > 0) await EmitStackAsync(stacker, pending.Dequeue(), cancellationToken).ConfigureAwait(false);
}
private async Task EmitStackAsync(TemporalStacker stacker, PlannedFrame planned, CancellationToken cancellationToken)
{
var output = new ImageBuffer(_geometry.OutputWidth, _geometry.OutputHeight, 3, clear: false);
try
{
stacker.Render(output, cancellationToken);
}
catch
{
output.Dispose();
throw;
}
await EmitAsync(output, planned.Duration90k).ConfigureAwait(false);
}
/// <summary>The picture of one planned frame at the output size (a new buffer owned by the caller).</summary>
private async Task<ImageBuffer> RenderFrameAsync(PlannedFrame planned, bool blur, CancellationToken cancellationToken)
{
if (planned.Fraction == 0)
{
var frame = await PreparedAsync(planned.From, cancellationToken).ConfigureAwait(false);
if (blur && BlurPair(planned.From) is { } pair && BlurFraction(pair.From, pair.To, planned.Speed) is var fraction and > 0)
{
var flows = await FlowAsync(pair.From, pair.To, needBackward: false, cancellationToken).ConfigureAwait(false);
frame = await PreparedAsync(planned.From, cancellationToken).ConfigureAwait(false);
return Blurred(frame, flows.Forward, fraction, cancellationToken);
}
return frame.Clone();
}
var pairFlows = await FlowAsync(planned.From, planned.To, needBackward: true, cancellationToken).ConfigureAwait(false);
var a = await PreparedAsync(planned.From, cancellationToken).ConfigureAwait(false);
var b = await PreparedAsync(planned.To, cancellationToken).ConfigureAwait(false);
var synthesised = new ImageBuffer(a.Width, a.Height, a.Channels, clear: false);
try
{
FrameInterpolator.Synthesize(a, b, pairFlows.Forward, pairFlows.Backward!, planned.Fraction, synthesised, cancellationToken: cancellationToken);
var fraction = blur ? BlurFraction(planned.From, planned.To, planned.Speed) : 0;
if (fraction <= 0) return synthesised;
using (synthesised) return Blurred(synthesised, pairFlows.Forward, fraction, cancellationToken);
}
catch
{
synthesised.Dispose();
throw;
}
}
private ImageBuffer Blurred(ImageBuffer source, MotionField flow, double fraction, CancellationToken cancellationToken)
{
var output = new ImageBuffer(source.Width, source.Height, source.Channels, clear: false);
try
{
_blur.Render(source, flow, fraction, output, cancellationToken);
return output;
}
catch
{
output.Dispose();
throw;
}
}
/// <summary>Continuous neighbours whose flow describes the motion at <paramref name="index"/>.</summary>
private (int From, int To)? BlurPair(int index)
{
var next = _plan.NextContinuous(index);
if (next >= 0) return (index, next);
var previous = _plan.PreviousContinuous(index);
return previous >= 0 ? (previous, index) : null;
}
/// <summary>
/// Fraction of the <paramref name="from"/>→<paramref name="to"/> flow to smear: the target shutter is relative to the
/// output period, which spans <paramref name="speed"/> source intervals, and the camera's own exposure already
/// blurred <see cref="ShutterAngle.FromExposure"/> of one interval (√(target² − real²) composition, §11.1).
/// </summary>
private double BlurFraction(int from, int to, double speed)
{
var steps = to - from;
if (steps <= 0) return 0;
var real = 0.0;
var info = _input.Frames[from];
if (info.ExposureTime is > 0 and var exposure && info.CapturedAt is { } t0 && _input.Frames[to].CapturedAt is { } t1 && t1 > t0)
real = double.Min(360, ShutterAngle.FromExposure(exposure, (t1 - t0).TotalSeconds / steps));
return ShutterAngle.BlurFraction(_targetShutter * double.Clamp(double.Abs(speed), 0, MaxBlurSpeed), real) / steps;
}
private async Task<FlowPair> FlowAsync(int from, int to, bool needBackward, CancellationToken cancellationToken)
{
if (_flows.TryGet(from, to, needBackward, out var cached)) return cached;
var a = await PreparedAsync(from, cancellationToken).ConfigureAwait(false);
var b = await PreparedAsync(to, cancellationToken).ConfigureAwait(false);
_flowEngine ??= new OpticalFlowEngine(_flowQuality);
FlowPair flows;
if (needBackward)
{
var (forward, backward) = _flowEngine.ComputeBidirectional(a, b, cancellationToken);
flows = new FlowPair(forward, backward);
}
else
{
flows = new FlowPair(_flowEngine.Compute(a, b, cancellationToken), null);
}
_flows.Add(from, to, flows);
return flows;
}
/// <summary>Source frame <paramref name="index"/> decoded, exposure-corrected and warped to the output size (cached).</summary>
private async Task<ImageBuffer> PreparedAsync(int index, CancellationToken cancellationToken)
{
if (_prepared.TryGet(index, out var cached)) return cached;
var raw = await _input.Source.GetFrameAsync(index, _workingEdge, DecodePurpose.Render, cancellationToken).ConfigureAwait(false);
ImageBuffer prepared;
try
{
raw = Rgb(raw);
ApplyExposure(raw, index);
var settings = _geometry.For(raw.Width, raw.Height, index, _corrections.StabilizationAt(index, raw.Width, raw.Height));
prepared = GeometryStage.Apply(raw, settings, cancellationToken);
}
finally
{
raw.Dispose();
}
_prepared.Add(index, prepared);
return prepared;
}
/// <summary>Gray sources become RGB and alpha is dropped, so every stage and encoder sees three channels.</summary>
private static ImageBuffer Rgb(ImageBuffer frame)
{
if (frame.Channels == 3) return frame;
using (frame)
{
if (frame.Channels == 1) return PixelConvert.GrayToRgb(frame);
var rgb = new ImageBuffer(frame.Width, frame.Height, 3, clear: false);
frame.Data[..(3 * frame.PlaneLength)].CopyTo(rgb.Data);
return rgb;
}
}
private void ApplyExposure(ImageBuffer frame, int index)
{
var gains = _corrections.WhiteBalance?[index];
if (_corrections is { Regions: { } mask, SkyEv: { } sky, LandEv: { } land })
{
if (_mask is null || _mask.Width != frame.Width || _mask.Height != frame.Height) _mask = mask.Resample(frame.Width, frame.Height);
ExposureProcessor.ApplyRegion(frame, _mask.Sky, sky[index], land[index], gains);
return;
}
var ev = _corrections.ExposureEv[index];
if (ev != 0 || (gains is { } g && g != ChannelGains.Identity)) ExposureProcessor.Apply(frame, ev, gains);
}
/// <summary>Applies the knee and hands the frame to the encoder once the previous frame is encoded; owns <paramref name="frame"/>.</summary>
private async Task EmitAsync(ImageBuffer frame, long duration90k)
{
ImageBuffer? preview = null;
try
{
await FlushEncodingAsync().ConfigureAwait(false);
if (_knee is { } knee) ExposureProcessor.Apply(frame, 0, null, knee);
_done++;
if (_options.PreviewInterval > 0 && (_done - 1) % _options.PreviewInterval == 0) preview = Resampler.Thumbnail(frame, _options.PreviewLongEdge);
}
catch
{
frame.Dispose();
throw;
}
var session = _session!;
_encoding = Task.Run(() =>
{
using (frame) session.WriteFrame(frame, duration90k);
}, CancellationToken.None);
if (_progress is not null)
{
var fps = Fps();
_progress.Report(new RenderProgress(RenderStage.Rendering, _done, _plan.Frames.Count, fps, _clock.Elapsed,
fps > 0 ? TimeSpan.FromSeconds((_plan.Frames.Count - _done) / fps) : null, preview));
}
else
{
preview?.Dispose();
}
}
private double Fps() => _done / double.Max(_clock.Elapsed.TotalSeconds, 1e-6);
/// <summary>Waits for the encode in flight; its failure propagates here (once).</summary>
private async Task FlushEncodingAsync()
{
var encoding = _encoding;
_encoding = null;
if (encoding is not null) await encoding.ConfigureAwait(false);
}
/// <summary>After a failure: waits for the encode in flight and logs (never throws) a second error.</summary>
private async Task ObserveEncodingAsync()
{
try
{
await FlushEncodingAsync().ConfigureAwait(false);
}
catch (Exception ex)
{
Log.Warning(RenderPipeline.LogCategory, "The encoder also failed while the render was stopping", ex);
}
}
}
+444
View File
@@ -0,0 +1,444 @@
using Titano.Core.Export;
using Titano.Core.Mathematics;
using Titano.Core.Project;
using Titano.Core.Video;
namespace Titano.Core.Render;
[Flags]
public enum PlannedFrameFlags
{
None = 0,
/// <summary>Synthesised between two included source frames from the motion field.</summary>
Interpolated = 1,
/// <summary>Shown for more than one output frame period.</summary>
Held = 2,
}
/// <summary>One output frame of a <see cref="RenderPlan"/>.</summary>
/// <param name="SourcePosition">Source frame index; fractional for synthesised frames (it may fall on an excluded frame).</param>
/// <param name="From">Included source frame at or before the position.</param>
/// <param name="To">Included source frame after the position; equals <paramref name="From"/> for whole frames.</param>
/// <param name="Fraction">Blend position between <paramref name="From"/> (0) and <paramref name="To"/> (1); 0 for whole frames.</param>
/// <param name="Start90k">Presentation time on the 90 kHz clock.</param>
/// <param name="Duration90k">Display duration on the 90 kHz clock.</param>
/// <param name="StartSlot">First output frame period at <see cref="RenderPlan.FrameRate"/>.</param>
/// <param name="Slots">Output frame periods covered (more than one = held).</param>
/// <param name="Speed">Source frames advanced per output frame period towards the next planned frame (scales motion blur).</param>
public readonly record struct PlannedFrame(
double SourcePosition,
int From,
int To,
double Fraction,
long Start90k,
long Duration90k,
int StartSlot,
int Slots,
double Speed,
PlannedFrameFlags Flags)
{
public bool IsInterpolated => (Flags & PlannedFrameFlags.Interpolated) != 0;
public bool IsHeld => (Flags & PlannedFrameFlags.Held) != 0;
}
/// <summary>Rules of the timing modes (documented defaults; BRIEF §11.1).</summary>
public sealed record RenderPlanOptions
{
public static RenderPlanOptions Default { get; } = new();
/// <summary>An interval longer than this multiple of the median capture interval is a gap: Adaptive compresses
/// it and motion (blur, synthesis) is treated as discontinuous across it.</summary>
public double GapFactor { get; init; } = 3;
/// <summary>Adaptive: longest display of a compressed gap, in playback frames (gaps are shown as
/// GapFactor + log2(ratio / GapFactor) frames up to this cap).</summary>
public double MaxGapFrames { get; init; } = 5;
/// <summary>Adaptive: an interval of at least this multiple of the median and <see cref="MinimumPauseSeconds"/> is a
/// deliberate pause and becomes a fixed visual cut.</summary>
public double PauseFactor { get; init; } = 20;
public double MinimumPauseSeconds { get; init; } = 120;
/// <summary>Adaptive: video seconds the frame before a deliberate pause stays on screen.</summary>
public double PauseCutSeconds { get; init; } = 0.2;
/// <summary>Interpolated: most consecutive missing (or excluded) frames synthesised in one gap; longer gaps are cuts.</summary>
public int MaxSynthesizedFrames { get; init; } = 3;
}
/// <summary>Figures for the Time tab's plan chart.</summary>
/// <param name="SourceFrames">Frames in the sequence.</param>
/// <param name="ExcludedFrames">Frames excluded by the user.</param>
/// <param name="ShownFrames">Included frames shown whole at least once.</param>
/// <param name="SkippedFrames">Included frames never shown nor used for synthesis (dropped by speed-ups).</param>
/// <param name="OutputFrames">Planned frames (held frames count once).</param>
/// <param name="OutputSlots">Output frame periods at the plan frame rate.</param>
/// <param name="HeldFrames">Planned frames covering several periods.</param>
/// <param name="InterpolatedFrames">Planned frames synthesised between two source frames.</param>
/// <param name="Cuts">Motion discontinuities (gaps, pauses, long exclusion runs).</param>
/// <param name="MedianIntervalSeconds">Median capture interval, when capture times are known.</param>
public sealed record RenderPlanStatistics(
int SourceFrames,
int ExcludedFrames,
int ShownFrames,
int SkippedFrames,
int OutputFrames,
int OutputSlots,
int HeldFrames,
int InterpolatedFrames,
int Cuts,
double DurationSeconds,
double MinimumSpeed,
double MaximumSpeed,
double? MedianIntervalSeconds);
/// <summary>
/// The list of output frames of a render (BRIEF §11.1): every timing mode produces planned frames with a (possibly
/// fractional) source position and a duration on the output frame grid.
/// <list type="bullet">
/// <item>The playback rate (<see cref="TimingSettings.FrameRate"/>, default the output rate) is how many source frames
/// one second of video shows; the output grid is the export frame rate.</item>
/// <item>Constant: every included frame lasts one playback frame (whole frames only).</item>
/// <item>Adaptive: a frame lasts its capture interval in median intervals; intervals up to <see cref="RenderPlanOptions.GapFactor"/>
/// are kept proportional (bursts play faster, small gaps are held), longer gaps are compressed logarithmically and
/// capped, deliberate pauses become a fixed cut of <see cref="RenderPlanOptions.PauseCutSeconds"/>; unknown or
/// non-positive intervals count as one.</item>
/// <item>Interpolated: like Constant, but gaps of up to <see cref="RenderPlanOptions.MaxSynthesizedFrames"/> missing or
/// excluded frames get their periods back with synthesised in-betweens, and slower-than-real-time playback is
/// synthesised rather than held.</item>
/// <item>Remapped: a Fritsch–Carlson monotone spline through <see cref="TimingSettings.RemapCurve"/> maps output time to
/// source time (both 0–1); fractional positions are synthesised.</item>
/// </list>
/// <see cref="TimingSettings.FitToSeconds"/> rescales the output time axis. Each output period shows one picture
/// (synthesised stretches sampled at the period start, whole frames at its centre); consecutive periods showing the
/// same picture merge into one held frame. Durations are differences of the rounded 90 kHz times of period boundaries,
/// so they add up exactly to the total.
/// </summary>
public sealed class RenderPlan
{
private const double SnapEpsilon = 1e-6;
private readonly bool[] _cutBefore;
private readonly int[] _includedOrder;
private RenderPlan(TimingMode mode, Rational frameRate, double playbackRate, PlannedFrame[] frames, int slots, int[] included,
bool[] cutBefore, RenderPlanStatistics statistics, IReadOnlyList<string> warnings)
{
Mode = mode;
FrameRate = frameRate;
PlaybackRate = playbackRate;
Frames = frames;
SlotCount = slots;
Duration90k = TicksAt(frameRate, slots);
IncludedFrames = included;
_cutBefore = cutBefore;
_includedOrder = new int[cutBefore.Length];
Array.Fill(_includedOrder, -1);
for (var k = 0; k < included.Length; k++) _includedOrder[included[k]] = k;
Statistics = statistics;
Warnings = warnings;
}
public TimingMode Mode { get; }
/// <summary>Output frame rate (the grid of every duration).</summary>
public Rational FrameRate { get; }
/// <summary>Source frames per second of video before fitting.</summary>
public double PlaybackRate { get; }
public IReadOnlyList<PlannedFrame> Frames { get; }
/// <summary>Output frame periods covered by the plan.</summary>
public int SlotCount { get; }
/// <summary>Exact total duration on the 90 kHz clock.</summary>
public long Duration90k { get; }
public double DurationSeconds => Duration90k / 90000.0;
/// <summary>Source indices that are not excluded, ascending.</summary>
public IReadOnlyList<int> IncludedFrames { get; }
public RenderPlanStatistics Statistics { get; }
/// <summary>Localisation keys of planning remarks (e.g. Adaptive without capture times).</summary>
public IReadOnlyList<string> Warnings { get; }
/// <summary>True when motion is discontinuous between <paramref name="sourceIndex"/> and the included frame before it.</summary>
public bool IsCutBefore(int sourceIndex) => _cutBefore[sourceIndex];
/// <summary>The included frame after <paramref name="sourceIndex"/> with continuous motion, or −1.</summary>
public int NextContinuous(int sourceIndex)
{
var k = _includedOrder[sourceIndex];
if (k < 0 || k + 1 >= IncludedFrames.Count) return -1;
var next = IncludedFrames[k + 1];
return _cutBefore[next] ? -1 : next;
}
/// <summary>The included frame before <paramref name="sourceIndex"/> with continuous motion, or −1.</summary>
public int PreviousContinuous(int sourceIndex)
{
var k = _includedOrder[sourceIndex];
return k <= 0 || _cutBefore[sourceIndex] ? -1 : IncludedFrames[k - 1];
}
/// <summary>Start of output period <paramref name="slot"/> on the 90 kHz clock, rounded half up.</summary>
public static long TicksAt(Rational frameRate, long slot) =>
(slot * 90000L * frameRate.Denominator * 2 + frameRate.Numerator) / (2L * frameRate.Numerator);
/// <summary>Builds the plan for a sequence.</summary>
/// <param name="captureTimes">Capture time per source frame (clock-corrected when available, e.g.
/// <c>LightAnalysisReport.AdjustedTimes</c>); null for unknown.</param>
/// <param name="project">Timing settings and excluded frames.</param>
/// <param name="frameRate">Output (encoded) frame rate.</param>
public static RenderPlan Build(IReadOnlyList<DateTime?> captureTimes, ProjectSettings project, Rational frameRate, RenderPlanOptions? options = null)
{
ArgumentNullException.ThrowIfNull(captureTimes);
ArgumentNullException.ThrowIfNull(project);
if (frameRate.Numerator <= 0 || frameRate.Denominator <= 0) throw new ArgumentOutOfRangeException(nameof(frameRate));
options ??= RenderPlanOptions.Default;
var n = captureTimes.Count;
var timing = project.Timing;
var mode = ProjectValues.Get(timing.Mode, TimingMode.Constant);
var warnings = new List<string>();
var playbackText = timing.FrameRate.Resolve(string.Empty);
var playback = FrameRateText.TryParse(playbackText, out var rate) ? rate.Value : frameRate.Value;
if (playbackText.Length > 0 && rate.Numerator == 0) warnings.Add("Export.Plan.FrameRateIgnored");
var excluded = new bool[n];
foreach (var i in project.ExcludedFrames)
{
if ((uint)i < (uint)n) excluded[i] = true;
}
var included = new List<int>(n);
for (var i = 0; i < n; i++)
{
if (!excluded[i]) included.Add(i);
}
var median = MedianInterval(captureTimes);
if (mode is TimingMode.Adaptive or TimingMode.Interpolated && median is null) warnings.Add("Export.Plan.NoCaptureTimes");
var cutBefore = new bool[n];
var entries = Timeline(captureTimes, included, mode, playback, median, options, cutBefore);
if (entries.Length == 0)
{
warnings.Add("Export.Plan.NoFrames");
var empty = new RenderPlanStatistics(n, n - included.Count, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, median);
return new RenderPlan(mode, frameRate, playback, [], 0, [.. included], cutBefore, empty, warnings);
}
var total = entries[^1].Start + entries[^1].Length;
var seconds = timing.FitToSeconds is { } fit && fit > 0 ? fit : total / playback;
var slots = (int)long.Clamp((long)double.Round(seconds * frameRate.Value), 1, int.MaxValue / 2);
var remap = mode == TimingMode.Remapped ? RemapSpline(timing.RemapCurve, warnings) : null;
var frames = new List<PlannedFrame>();
Sample? open = null;
var openStart = 0;
for (var k = 0; k <= slots; k++)
{
Sample? sample = null;
if (k < slots)
{
sample = Locate(entries, TimelinePosition(k, slots, total, remap), TimelinePosition(k + 0.5, slots, total, remap), total);
if (open is { } current && current.SameAs(sample.Value)) continue;
}
if (open is { } done) frames.Add(Planned(done, openStart, k - openStart, frameRate));
open = sample;
openStart = k;
}
var planned = frames.ToArray();
AssignSpeeds(planned);
var statistics = Summarise(n, n - included.Count, included, planned, slots, cutBefore, frameRate, median);
return new RenderPlan(mode, frameRate, playback, planned, slots, [.. included], cutBefore, statistics, warnings);
}
/// <summary>A stretch of the playback timeline shown by one included frame.</summary>
/// <param name="Start">Start in playback frames.</param>
/// <param name="Length">Length in playback frames (> 0).</param>
/// <param name="Index">Source index shown at the start.</param>
/// <param name="Next">Next included source index, −1 for the last.</param>
/// <param name="Continuous">The position moves linearly towards <paramref name="Next"/> across the stretch (synthesis).</param>
private readonly record struct Entry(double Start, double Length, int Index, int Next, bool Continuous);
private readonly record struct Sample(int From, int To, double Fraction, double Position)
{
public bool SameAs(Sample other) => From == other.From && To == other.To && Fraction == other.Fraction;
}
private static Entry[] Timeline(IReadOnlyList<DateTime?> times, List<int> included, TimingMode mode, double playback, double? median,
RenderPlanOptions options, bool[] cutBefore)
{
var entries = new Entry[included.Count];
double start = 0;
for (var k = 0; k < included.Count; k++)
{
var index = included[k];
var next = k + 1 < included.Count ? included[k + 1] : -1;
double length = 1;
var continuous = false;
if (next >= 0)
{
var seconds = times[index] is { } a && times[next] is { } b ? (b - a).TotalSeconds : double.NaN;
var ratio = median is { } m && seconds > 0 ? seconds / m : double.NaN;
var steps = next - index;
var gap = double.Max(double.IsNaN(ratio) ? steps : ratio, steps) > options.GapFactor;
switch (mode)
{
case TimingMode.Adaptive:
length = AdaptiveLength(ratio, seconds, playback, options, ref gap);
break;
case TimingMode.Interpolated:
var periods = int.Max(steps, double.IsNaN(ratio) ? 1 : (int)double.Min(double.Round(ratio), int.MaxValue / 2));
gap = periods - 1 > options.MaxSynthesizedFrames;
if (!gap)
{
length = periods;
continuous = true;
}
break;
case TimingMode.Remapped:
continuous = !gap;
break;
}
cutBefore[next] = gap;
}
entries[k] = new Entry(start, length, index, next, continuous);
start += length;
}
return entries;
}
private static double AdaptiveLength(double ratio, double seconds, double playback, RenderPlanOptions options, ref bool gap)
{
if (double.IsNaN(ratio)) return 1;
if (ratio <= options.GapFactor) return ratio;
gap = true;
if (ratio >= options.PauseFactor && seconds >= options.MinimumPauseSeconds) return double.Max(options.PauseCutSeconds * playback, 1e-3);
return double.Min(options.MaxGapFrames, options.GapFactor + double.Log2(ratio / options.GapFactor));
}
/// <summary>Playback-timeline position of output period <paramref name="slot"/> (fractional slots address its interior).</summary>
private static double TimelinePosition(double slot, int slots, double total, MonotoneSpline? remap)
{
var x = slot / slots;
return remap is null ? x * total : double.Clamp(remap.Evaluate(x), 0, 1) * total;
}
/// <summary>
/// The picture of an output period. Synthesised stretches are sampled at the period start (so equal rates give whole
/// frames); whole-frame stretches at the period centre, which rounds every frame boundary to the nearest period
/// (ties keep the earlier frame, so a 2× speed-up shows frames 0, 2, 4…).
/// </summary>
private static Sample Locate(Entry[] entries, double start, double centre, double total)
{
var e = entries[Find(entries, double.Clamp(start, 0, total), atBoundary: true)];
if (e.Continuous && e.Next >= 0)
{
var fraction = double.Clamp((start - e.Start) / e.Length, 0, 1);
if (fraction < SnapEpsilon) return new Sample(e.Index, e.Index, 0, e.Index);
if (fraction > 1 - SnapEpsilon) return new Sample(e.Next, e.Next, 0, e.Next);
return new Sample(e.Index, e.Next, fraction, e.Index + fraction * (e.Next - e.Index));
}
var index = entries[Find(entries, double.Clamp(centre, 0, total), atBoundary: false)].Index;
return new Sample(index, index, 0, index);
}
/// <summary>Entry containing <paramref name="u"/>; a position within 1e-9 of a boundary belongs to the entry starting
/// there when <paramref name="atBoundary"/>, else to the one ending there.</summary>
private static int Find(Entry[] entries, double u, bool atBoundary)
{
var limit = atBoundary ? u + 1e-9 : u - 1e-9;
int lo = 0, hi = entries.Length - 1;
while (lo < hi)
{
var mid = (lo + hi + 1) >> 1;
if (atBoundary ? entries[mid].Start <= limit : entries[mid].Start < limit) lo = mid;
else hi = mid - 1;
}
return lo;
}
private static PlannedFrame Planned(Sample s, int startSlot, int slots, Rational rate)
{
var start = TicksAt(rate, startSlot);
var flags = (s.Fraction > 0 ? PlannedFrameFlags.Interpolated : PlannedFrameFlags.None) | (slots > 1 ? PlannedFrameFlags.Held : PlannedFrameFlags.None);
return new PlannedFrame(s.Position, s.From, s.To, s.Fraction, start, TicksAt(rate, startSlot + slots) - start, startSlot, slots, 0, flags);
}
private static void AssignSpeeds(PlannedFrame[] frames)
{
for (var k = 0; k + 1 < frames.Length; k++)
frames[k] = frames[k] with { Speed = (frames[k + 1].SourcePosition - frames[k].SourcePosition) / frames[k].Slots };
if (frames.Length > 1) frames[^1] = frames[^1] with { Speed = frames[^2].Speed };
else if (frames.Length == 1) frames[0] = frames[0] with { Speed = 1 };
}
/// <summary>Sorted, clamped and made non-decreasing so the spline (and the remap) is monotone.</summary>
private static MonotoneSpline? RemapSpline(IReadOnlyList<CurvePoint> curve, List<string> warnings)
{
var points = curve.Where(p => double.IsFinite(p.X) && double.IsFinite(p.Y))
.Select(p => (X: double.Clamp(p.X, 0, 1), Y: double.Clamp(p.Y, 0, 1)))
.OrderBy(p => p.X)
.ToList();
if (points.Count == 0) return null;
var xs = new List<double>(points.Count);
var ys = new List<double>(points.Count);
var adjusted = false;
foreach (var (x, y) in points)
{
var value = y;
if (ys.Count > 0 && value < ys[^1])
{
value = ys[^1];
adjusted = true;
}
if (xs.Count > 0 && x == xs[^1])
{
ys[^1] = double.Max(ys[^1], value);
continue;
}
xs.Add(x);
ys.Add(value);
}
if (adjusted) warnings.Add("Export.Plan.RemapNotMonotonic");
return new MonotoneSpline(xs.ToArray(), ys.ToArray());
}
private static double? MedianInterval(IReadOnlyList<DateTime?> times)
{
var intervals = new List<double>(times.Count);
for (var i = 1; i < times.Count; i++)
{
if (times[i - 1] is { } a && times[i] is { } b && b > a) intervals.Add((b - a).TotalSeconds);
}
return intervals.Count == 0 ? null : Mathematics.Statistics.Median(intervals.ToArray());
}
private static RenderPlanStatistics Summarise(int sourceFrames, int excludedFrames, List<int> included, PlannedFrame[] frames, int slots,
bool[] cutBefore, Rational rate, double? median)
{
var shown = new HashSet<int>();
var used = new HashSet<int>();
int held = 0, interpolated = 0;
double minSpeed = double.PositiveInfinity, maxSpeed = double.NegativeInfinity;
foreach (var f in frames)
{
used.Add(f.From);
used.Add(f.To);
if (f.Fraction == 0) shown.Add(f.From);
if (f.IsHeld) held++;
if (f.IsInterpolated) interpolated++;
minSpeed = double.Min(minSpeed, f.Speed);
maxSpeed = double.Max(maxSpeed, f.Speed);
}
var cuts = cutBefore.Count(c => c);
return new RenderPlanStatistics(sourceFrames, excludedFrames, shown.Count, included.Count - used.Count, frames.Length, slots, held, interpolated,
cuts, TicksAt(rate, slots) / 90000.0, frames.Length > 0 ? minSpeed : 0, frames.Length > 0 ? maxSpeed : 0, median);
}
}
+459
View File
@@ -0,0 +1,459 @@
using System.Diagnostics;
using System.Globalization;
using Titano.Core.Analysis;
using Titano.Core.Imaging;
using Titano.Core.Imaging.Geometry;
using Titano.Core.Motion;
using Titano.Core.Project;
namespace Titano.Core.Render;
/// <summary>Diagnostics of <see cref="RenderPreparation"/> for the editor's measuring tools and the render log.</summary>
public sealed record RenderPreparationReport
{
/// <summary>Frames decoded by the preparation pass (0 when cached analysis covered everything needed).</summary>
public int MeasuredFrames { get; init; }
public DeflickerDiagnostics? Deflicker { get; init; }
/// <summary>Holy-grail transitions (received and ignored steps).</summary>
public IReadOnlyList<ExposureTransition> Transitions { get; init; } = [];
/// <summary>Largest frame-to-frame change of the holy-grail target, in EV.</summary>
public double? MaxTargetStepEv { get; init; }
public double? ShakeRms { get; init; }
public RegionMethod? RegionMethod { get; init; }
public IReadOnlyList<RenderWarning> Warnings { get; init; } = [];
}
/// <summary>Per-source-frame corrections computed once per render (every array has one entry per source frame).</summary>
public sealed record RenderCorrections
{
public required int FrameCount { get; init; }
/// <summary>Measured log2 luminance (NaN where not measured): the amber curve of the Exposure chart.</summary>
public required double[] MeasuredLogLuminance { get; init; }
/// <summary>Global exposure correction in EV, including the project's exposure offset.</summary>
public required double[] ExposureEv { get; init; }
/// <summary>White-balance gains; null when smoothing is off.</summary>
public ChannelGains[]? WhiteBalance { get; init; }
/// <summary>Sky/land mask; when set, <see cref="SkyEv"/> and <see cref="LandEv"/> replace <see cref="ExposureEv"/>.</summary>
public RegionMask? Regions { get; init; }
public double[]? SkyEv { get; init; }
public double[]? LandEv { get; init; }
/// <summary>Stabiliser corrections (source → stabilised) in pixels of a <see cref="StabilizationWidth"/>-wide frame.</summary>
public Affine2D[]? Stabilization { get; init; }
public int StabilizationWidth { get; init; }
public int StabilizationHeight { get; init; }
/// <summary>Zoom applied about the centre so stabilisation borders stay outside the picture (1 = none).</summary>
public double StabilizationZoom { get; init; } = 1;
public RenderPreparationReport Report { get; init; } = new();
/// <summary>Target log2 luminance (measured + correction): the accent curve of the Exposure chart.</summary>
public double[] TargetLogLuminance()
{
var target = new double[FrameCount];
for (var i = 0; i < FrameCount; i++) target[i] = MeasuredLogLuminance[i] + ExposureEv[i];
return target;
}
/// <summary>The stabiliser correction of frame <paramref name="index"/> for a frame of <paramref name="width"/>×<paramref name="height"/>.</summary>
public Affine2D StabilizationAt(int index, int width, int height)
{
if (Stabilization is null) return Affine2D.Identity;
var c = Stabilization[index];
if (c.IsIdentity() || (width == StabilizationWidth && height == StabilizationHeight)) return c;
// Pixel-centre scaling between the two frame sizes: x' = (x + ½)·s − ½.
double sx = (double)width / StabilizationWidth, sy = (double)height / StabilizationHeight;
var toFrame = new Affine2D(sx, 0, 0, sy, (sx - 1) / 2, (sy - 1) / 2);
return toFrame * c * toFrame.Invert();
}
}
/// <summary>
/// The pass over the sequence that a render needs before its first frame (BRIEF §11.1–§11.2): luminance, colour and
/// region series for deflicker / holy grail / white balance / region deflicker, and the stabilisation path. Values the
/// cached <see cref="PrecomputedAnalysis"/> provides are reused; the rest is measured on frames decoded at
/// <see cref="RenderOptions.AnalysisLongEdge"/> one at a time (memory does not grow with the sequence).
/// <list type="bullet">
/// <item>Modules switch on only when their setting resolves to true; Auto without advice changes nothing.</item>
/// <item>Deflicker keeps metadata exposure steps (as intentional offsets); holy grail turns the received steps into
/// ramps (alone, or on top of deflicker); region deflicker gives sky and land their own curves.</item>
/// <item>Stabilisation analyses the included frames only and zooms in by 1 / crop scale (at most 1 / 0.75) to hide borders.</item>
/// </list>
/// </summary>
public static class RenderPreparation
{
/// <summary>Smallest stabilisation crop scale compensated by zooming; below it borders may show.</summary>
public const double MinimumCropScale = 0.75;
/// <summary>Region masks below this confidence are not used when the region mode is Auto.</summary>
public const double MinimumRegionConfidence = 0.3;
public static async Task<RenderCorrections> PrepareAsync(RenderInput input, RenderOptions? options = null, IProgress<RenderProgress>? progress = null,
CancellationToken cancellationToken = default)
{
ArgumentNullException.ThrowIfNull(input);
options ??= RenderOptions.Default;
await Task.CompletedTask.ConfigureAwait(ConfigureAwaitOptions.ForceYielding);
var n = input.Source.FrameCount;
if (input.Frames.Count != n) throw new ArgumentException("One metadata entry per source frame is required.", nameof(input));
var exposure = input.Project.Exposure;
var motion = input.Project.Motion;
var cached = input.Analysis;
var warnings = new List<RenderWarning>();
var included = Included(input.Project.ExcludedFrames, n);
var excluded = new bool[n];
Array.Fill(excluded, true);
foreach (var i in included) excluded[i] = false;
var deflicker = ProjectValues.Get(exposure.Deflicker, false);
var holyGrail = ProjectValues.Get(exposure.HolyGrail, false);
var regionMode = deflicker ? ProjectValues.Get(exposure.Regions, RegionMode.Off) : RegionMode.Off;
var whiteBalance = ProjectValues.Get(exposure.WhiteBalanceSmoothing, false);
var stabilize = ProjectValues.Get(motion.Stabilize, false);
var smoothing = ProjectValues.Get(motion.StabilizeSmoothing, new StabilizerOptions().SmoothingSigma);
var luminance = deflicker || holyGrail ? Valid(cached?.LogLuminance, excluded) : null;
var measureLuminance = (deflicker || holyGrail) && luminance is null;
double[]? red = null, green = null, blue = null;
if (whiteBalance && Valid(cached?.MeanRed, excluded) is { } r && Valid(cached?.MeanGreen, excluded) is { } g && Valid(cached?.MeanBlue, excluded) is { } b)
(red, green, blue) = (r, g, b);
var measureColour = whiteBalance && red is null;
RegionMask? mask = null;
double[]? sky = null, land = null;
if (regionMode != RegionMode.Off && cached?.Regions is { } m && Valid(cached.SkyLogLuminance, excluded) is { } s && Valid(cached.LandLogLuminance, excluded) is { } l)
(mask, sky, land) = (m, s, l);
var stabilization = stabilize ? CachedStabilization(cached, n, smoothing) : null;
var measureStabilization = stabilize && stabilization is null;
if (regionMode != RegionMode.Off && mask is null && included.Count > 0)
{
mask = await SegmentAsync(input.Source, included, regionMode, options.AnalysisLongEdge, cancellationToken).ConfigureAwait(false);
if (mask is null) warnings.Add(new RenderWarning("Export.Render.RegionsUnavailable"));
else if (regionMode == RegionMode.Auto && mask.Confidence < MinimumRegionConfidence)
{
warnings.Add(new RenderWarning("Export.Render.RegionsUnreliable", mask.Confidence.ToString("0.00", CultureInfo.InvariantCulture)));
mask = null;
}
}
var measureRegions = mask is not null && sky is null;
var pass = new MeasurementPass(n, measureLuminance, measureColour, measureRegions ? mask : null, measureStabilization, smoothing);
if (pass.Needed)
{
await pass.RunAsync(input.Source, included, options.AnalysisLongEdge, progress, cancellationToken).ConfigureAwait(false);
luminance ??= pass.Luminance;
red ??= pass.Red;
green ??= pass.Green;
blue ??= pass.Blue;
sky ??= pass.Sky;
land ??= pass.Land;
if (measureStabilization)
{
stabilization = pass.SolveStabilization(included, n);
if (stabilization is null) warnings.Add(new RenderWarning("Export.Render.StabilizationUnavailable"));
}
}
return Combine(input, excluded, luminance, red, green, blue, mask, sky, land, stabilization, deflicker, holyGrail, pass.MeasuredFrames, warnings);
}
private static RenderCorrections Combine(RenderInput input, bool[] excluded, double[]? luminance, double[]? red, double[]? green, double[]? blue, RegionMask? mask,
double[]? sky, double[]? land, StabilizationData? stabilization, bool deflicker, bool holyGrail, int measured, List<RenderWarning> warnings)
{
var n = input.Source.FrameCount;
var exposure = input.Project.Exposure;
var ev = new double[n];
double[]? skyEv = null, landEv = null;
DeflickerDiagnostics? diagnostics = null;
HolyGrailResult? hg = null;
if (luminance is not null)
{
var options = new DeflickerOptions
{
Window = int.Max(3, ProjectValues.Get(exposure.DeflickerWindow, 0) is var w and > 0 ? w : RecommendedWindow(luminance)),
Strength = double.Clamp(ProjectValues.Get(exposure.DeflickerStrength, 1.0), 0, 1),
};
var evs = new double?[n];
// Excluded frames (test shots, bumps) must not create exposure steps.
for (var i = 0; i < n; i++) evs[i] = excluded[i] ? null : input.Frames[i].ExposureValue;
if (holyGrail)
{
var transition = ProjectValues.Get(exposure.TransitionLength, 0);
hg = HolyGrailEngine.Compute(luminance, evs, new HolyGrailOptions { TransitionFrames = transition > 0 ? transition : null, Deflicker = options });
}
var offsets = hg?.StepOffsets ?? DeflickerEngine.OffsetsFromExposure(evs);
if (deflicker && hg is not null)
{
Array.Copy(hg.CorrectionEv, ev, n);
diagnostics = hg.Deflicker.Diagnostics;
}
else if (deflicker)
{
var result = DeflickerEngine.Compute(luminance, options, offsets);
Array.Copy(result.CorrectionEv, ev, n);
diagnostics = result.Diagnostics;
}
else if (hg is not null)
{
for (var i = 0; i < n; i++) ev[i] = hg.SmoothedOffsets[i] - hg.StepOffsets[i];
}
if (mask is not null && sky is not null && land is not null)
{
var regions = RegionDeflicker.Compute(sky, land, options, offsets);
skyEv = new double[n];
landEv = new double[n];
for (var i = 0; i < n; i++)
{
var ramp = hg is null ? 0 : hg.SmoothedOffsets[i] - hg.StepOffsets[i];
skyEv[i] = regions.Sky.CorrectionEv[i] + ramp + exposure.ExposureOffsetEv;
landEv[i] = regions.Land.CorrectionEv[i] + ramp + exposure.ExposureOffsetEv;
}
}
}
for (var i = 0; i < n; i++) ev[i] += exposure.ExposureOffsetEv;
ChannelGains[]? gains = red is not null && green is not null && blue is not null ? WhiteBalanceSmoother.Smooth(red, green, blue).Gains : null;
var zoom = 1.0;
if (stabilization is not null)
{
zoom = 1 / double.Max(stabilization.CropScale, MinimumCropScale);
if (stabilization.CropScale < MinimumCropScale)
warnings.Add(new RenderWarning("Export.Render.StabilizationBorders", stabilization.CropScale.ToString("0.00", CultureInfo.InvariantCulture)));
}
var measuredLuminance = luminance ?? NaNs(n);
return new RenderCorrections
{
FrameCount = n,
MeasuredLogLuminance = measuredLuminance,
ExposureEv = ev,
WhiteBalance = gains,
Regions = skyEv is null ? null : mask,
SkyEv = skyEv,
LandEv = landEv,
Stabilization = stabilization?.Corrections,
StabilizationWidth = stabilization?.Width ?? 0,
StabilizationHeight = stabilization?.Height ?? 0,
StabilizationZoom = zoom,
Report = new RenderPreparationReport
{
MeasuredFrames = measured,
Deflicker = diagnostics,
Transitions = hg?.Transitions ?? [],
MaxTargetStepEv = hg?.MaxFrameStepEv,
ShakeRms = stabilization?.ShakeRms,
RegionMethod = skyEv is null ? null : mask!.Method,
Warnings = warnings,
},
};
}
/// <summary>Corrections for every source frame (identity for excluded ones) with the frame size they are measured in.</summary>
private sealed record StabilizationData(Affine2D[] Corrections, int Width, int Height, double CropScale, double ShakeRms);
private static StabilizationData? CachedStabilization(PrecomputedAnalysis? cached, int n, double smoothing)
{
if (cached?.Stabilization is not { } result || result.Corrections.Count != n || cached.StabilizationWidth <= 0 || cached.StabilizationHeight <= 0
|| double.Abs(cached.StabilizationSmoothing - smoothing) > 1e-9) return null;
return new StabilizationData([.. result.Corrections], cached.StabilizationWidth, cached.StabilizationHeight, result.CropScale, result.ShakeRms);
}
private static int RecommendedWindow(double[] luminance)
{
var finite = luminance.Where(double.IsFinite).ToArray();
return finite.Length >= 16 ? FlickerSpectrum.Analyze(finite).RecommendedWindow : DeflickerOptions.Default.Window;
}
private static List<int> Included(IReadOnlyList<int> excluded, int n)
{
var skip = new bool[n];
foreach (var i in excluded)
{
if ((uint)i < (uint)n) skip[i] = true;
}
var result = new List<int>(n);
for (var i = 0; i < n; i++)
{
if (!skip[i]) result.Add(i);
}
return result;
}
/// <summary>A copy of a cached series with excluded frames marked unusable, or null when it does not fit the sequence.</summary>
private static double[]? Valid(double[]? values, bool[] excluded)
{
if (values is null || values.Length != excluded.Length) return null;
var copy = (double[])values.Clone();
for (var i = 0; i < copy.Length; i++)
{
if (excluded[i]) copy[i] = double.NaN;
}
return copy;
}
private static double[] NaNs(int n)
{
var values = new double[n];
Array.Fill(values, double.NaN);
return values;
}
private static async Task<RegionMask?> SegmentAsync(IRenderFrameSource source, List<int> included, RegionMode mode, int longEdge, CancellationToken cancellationToken)
{
var options = new RegionSegmenterOptions
{
// Horizon mode accepts any detected horizon; Luminance mode lets the horizon win only when it is more confident.
MinimumHorizonConfidence = mode switch { RegionMode.Horizon => 0, RegionMode.Luminance => 2, _ => RegionSegmenterOptions.Default.MinimumHorizonConfidence },
};
var count = int.Min(options.MaxFrames, included.Count);
var frames = new List<ImageBuffer>(count);
try
{
for (var k = 0; k < count; k++)
{
var index = included[(int)((long)k * (included.Count - 1) / int.Max(1, count - 1))];
var frame = await source.GetFrameAsync(index, longEdge, DecodePurpose.Analysis, cancellationToken).ConfigureAwait(false);
frames.Add(frames.Count == 0 ? frame : Conform(frame, frames[0].Width, frames[0].Height));
}
return frames[0].Height < 8 ? null : RegionSegmenter.Segment(frames, options);
}
finally
{
foreach (var f in frames) f.Dispose();
}
}
/// <summary>Resizes <paramref name="frame"/> to the given size (disposing it) when a source returns frames of varying size.</summary>
internal static ImageBuffer Conform(ImageBuffer frame, int width, int height)
{
if (frame.Width == width && frame.Height == height) return frame;
try
{
return Resampler.Resize(frame, width, height);
}
finally
{
frame.Dispose();
}
}
/// <summary>One sequential pass that measures whatever the cache did not provide.</summary>
private sealed class MeasurementPass(int n, bool luminance, bool colour, RegionMask? regions, bool stabilization, double smoothing)
{
public bool Needed => luminance || colour || regions is not null || stabilization;
public int MeasuredFrames { get; private set; }
public double[]? Luminance { get; } = luminance ? NaNs(n) : null;
public double[]? Red { get; } = colour ? NaNs(n) : null;
public double[]? Green { get; } = colour ? NaNs(n) : null;
public double[]? Blue { get; } = colour ? NaNs(n) : null;
public double[]? Sky { get; } = regions is not null ? NaNs(n) : null;
public double[]? Land { get; } = regions is not null ? NaNs(n) : null;
private Stabilizer? _stabilizer;
public async Task RunAsync(IRenderFrameSource source, List<int> included, int longEdge, IProgress<RenderProgress>? progress, CancellationToken cancellationToken)
{
var clock = Stopwatch.StartNew();
RegionMask? fitted = null;
var stabilize = stabilization;
try
{
foreach (var index in included)
{
cancellationToken.ThrowIfCancellationRequested();
var frame = await source.GetFrameAsync(index, longEdge, DecodePurpose.Analysis, cancellationToken).ConfigureAwait(false);
using (frame)
{
if (Luminance is not null) Luminance[index] = FrameStatistics.MeasureLogLuminance(frame);
if (Red is not null) (Red[index], Green![index], Blue![index]) = Means(frame);
if (regions is not null && Sky is not null)
{
if (fitted is null || fitted.Width != frame.Width || fitted.Height != frame.Height) fitted = regions.Resample(frame.Width, frame.Height);
(Sky[index], Land![index]) = RegionDeflicker.Measure(frame, fitted);
}
if (stabilize) stabilize = AddToStabilizer(frame);
}
MeasuredFrames++;
if (progress is not null)
{
var elapsed = clock.Elapsed;
var fps = MeasuredFrames / double.Max(elapsed.TotalSeconds, 1e-6);
progress.Report(new RenderProgress(RenderStage.Preparing, MeasuredFrames, included.Count, fps, elapsed,
TimeSpan.FromSeconds((included.Count - MeasuredFrames) / fps)));
}
}
}
catch
{
_stabilizer?.Dispose();
_stabilizer = null;
throw;
}
if (!stabilize)
{
_stabilizer?.Dispose();
_stabilizer = null;
}
}
/// <summary>False when the frames are too small to stabilise.</summary>
private bool AddToStabilizer(ImageBuffer frame)
{
if (_stabilizer is null)
{
if (frame.Width < 16 || frame.Height < 16) return false;
_stabilizer = new Stabilizer(frame.Width, frame.Height, new StabilizerOptions { SmoothingSigma = smoothing });
}
if (frame.Width == _stabilizer.Width && frame.Height == _stabilizer.Height)
{
_stabilizer.AddFrame(frame);
return true;
}
using var resized = Resampler.Resize(frame, _stabilizer.Width, _stabilizer.Height);
_stabilizer.AddFrame(resized);
return true;
}
public StabilizationData? SolveStabilization(List<int> included, int frameCount)
{
var stabilizer = _stabilizer;
_stabilizer = null;
if (stabilizer is null) return null;
using (stabilizer)
{
if (stabilizer.FrameCount == 0) return null;
var result = stabilizer.Solve();
var corrections = new Affine2D[frameCount];
Array.Fill(corrections, Affine2D.Identity);
for (var k = 0; k < included.Count; k++) corrections[included[k]] = result.Corrections[k];
return new StabilizationData(corrections, stabilizer.Width, stabilizer.Height, result.CropScale, result.ShakeRms);
}
}
private static (double R, double G, double B) Means(ImageBuffer image)
{
var count = image.PlaneLength;
var r = Sum(image.Plane(0)) / count;
if (image.Channels < 3) return (r, r, r);
return (r, Sum(image.Plane(1)) / count, Sum(image.Plane(2)) / count);
}
private static double Sum(ReadOnlySpan<float> values)
{
double sum = 0;
foreach (var v in values) sum += v;
return sum;
}
}
}
+71
View File
@@ -0,0 +1,71 @@
using Titano.Core.Export;
using Titano.Core.Video;
namespace Titano.Core.Render;
/// <summary>A finished render, for the render history and the database (<see cref="Model.Render"/>).</summary>
public sealed record RenderResult
{
/// <summary>The output file, or folder for image sequences.</summary>
public required string OutputPath { get; init; }
/// <summary>Effective preset id (or <see cref="ExportResolver.CustomId"/>).</summary>
public required string PresetId { get; init; }
public required VideoCodec Codec { get; init; }
public ContainerFormat Container => VideoCodecInfo.DefaultContainer(Codec);
public required int Width { get; init; }
public required int Height { get; init; }
public required Rational FrameRate { get; init; }
public required double DurationSeconds { get; init; }
/// <summary>Output pictures rendered (held frames count once).</summary>
public required int FrameCount { get; init; }
/// <summary>Size of the file, or of every file of a sequence.</summary>
public required long Bytes { get; init; }
public required string EncoderName { get; init; }
public required bool Hardware { get; init; }
public required TimeSpan Elapsed { get; init; }
/// <summary>Plan, geometry, encoder and preparation remarks.</summary>
public IReadOnlyList<RenderWarning> Warnings { get; init; } = [];
/// <summary>The render-history entity.</summary>
/// <param name="presetName">Display name of the preset at render time.</param>
/// <param name="settingsJson">The project settings used (<see cref="Project.ProjectSettings.ToJson"/>).</param>
/// <param name="producedBy">Client or render-node name.</param>
public Model.Render ToEntity(Guid sequenceId, string presetName, string? settingsJson, string? producedBy) => new()
{
Id = Guid.CreateVersion7(),
SequenceId = sequenceId,
PresetName = presetName,
SettingsJson = settingsJson,
OutputPath = OutputPath,
Codec = Codec.ToString(),
Width = Width,
Height = Height,
Fps = FrameRate.Value,
DurationSeconds = DurationSeconds,
Bytes = Bytes,
Created = DateTimeOffset.UtcNow,
ProducedBy = producedBy,
};
/// <summary>Bytes of a file, or the total of the files in a folder.</summary>
internal static long SizeOf(string path)
{
if (File.Exists(path)) return new FileInfo(path).Length;
if (!Directory.Exists(path)) return 0;
long total = 0;
foreach (var file in new DirectoryInfo(path).EnumerateFiles("*", SearchOption.AllDirectories)) total += file.Length;
return total;
}
}
/// <summary>Outcome of one target of <see cref="RenderPipeline.RenderBatchAsync"/>: a result or the failure that stopped it.</summary>
public sealed record BatchItemResult(RenderTarget Target, RenderResult? Result, Exception? Error)
{
public bool Succeeded => Result is not null;
}
+83
View File
@@ -0,0 +1,83 @@
using Titano.Core.Export;
using Titano.Core.Project;
using Titano.Core.Video;
namespace Titano.Core.Render;
/// <summary>
/// What a render will do, decided before its first frame: output geometry, encoder (with its adjustments) and plan.
/// The Export tab uses it for the output size, encoder notices, plan chart and estimates.
/// </summary>
public sealed record RenderSetup
{
public required RenderTarget Target { get; init; }
public required RenderGeometry Geometry { get; init; }
public required EncoderSelection Encoder { get; init; }
public required RenderPlan Plan { get; init; }
/// <summary>Synthetic motion blur applies (it is off while stacking).</summary>
public bool MotionBlur { get; init; }
/// <summary>The preparation pass decodes frames (no corrections were supplied and a module needs measurements).</summary>
public bool NeedsPreparation { get; init; }
/// <summary>Geometry, plan and encoder remarks.</summary>
public IReadOnlyList<RenderWarning> Warnings { get; init; } = [];
/// <summary>Decides geometry, encoder and plan for one target.</summary>
/// <param name="corrections">Prepared corrections when available (their stabilisation zoom affects the decode size).</param>
public static RenderSetup Create(RenderInput input, RenderTarget target, IReadOnlyList<IVideoEncoderProvider> encoders, EncoderHost host,
RenderOptions? options = null, RenderCorrections? corrections = null)
{
ArgumentNullException.ThrowIfNull(input);
ArgumentNullException.ThrowIfNull(target);
ArgumentNullException.ThrowIfNull(encoders);
options ??= RenderOptions.Default;
if (input.Frames.Count != input.Source.FrameCount) throw new ArgumentException("One metadata entry per source frame is required.", nameof(input));
var project = input.Project;
var geometry = RenderGeometry.Create(project.Camera, target.Export, input.Source.Width, input.Source.Height,
corrections?.StabilizationZoom ?? 1, options.MaxWorkingLongEdge);
var selection = EncoderSelector.Select(target.Export.ToEncodeSettings(target.OutputPath, geometry.OutputWidth, geometry.OutputHeight), encoders, host);
geometry = geometry.WithOutputSize(selection.Settings.Width, selection.Settings.Height);
var times = new DateTime?[input.Frames.Count];
for (var i = 0; i < times.Length; i++) times[i] = input.Frames[i].CapturedAt;
var plan = RenderPlan.Build(times, project, selection.Settings.FrameRate, options.Plan);
var warnings = new List<RenderWarning>(geometry.Warnings);
warnings.AddRange(plan.Warnings.Select(k => new RenderWarning(k)));
warnings.AddRange(selection.Notices.Select(n => new RenderWarning(n.Key, n.Args)));
var stacking = project.Stack.Mode != StackSetting.None;
var blur = ProjectValues.Get(project.Motion.MotionBlur, false);
if (blur && stacking) warnings.Add(new RenderWarning("Export.Render.BlurOffWhileStacking"));
var exposure = project.Exposure;
var measuring = ProjectValues.Get(exposure.Deflicker, false) || ProjectValues.Get(exposure.HolyGrail, false)
|| ProjectValues.Get(exposure.WhiteBalanceSmoothing, false) || ProjectValues.Get(project.Motion.Stabilize, false);
return new RenderSetup
{
Target = target,
Geometry = geometry,
Encoder = selection,
Plan = plan,
MotionBlur = blur && !stacking,
NeedsPreparation = corrections is null && measuring,
Warnings = warnings,
};
}
/// <summary>The render's workload in the units of <see cref="ExportEstimator"/>.</summary>
public ExportWorkload Workload()
{
var edge = Geometry.WorkingLongEdge;
var shortEdge = (long)double.Round(edge * (double)int.Min(Geometry.SourceWidth, Geometry.SourceHeight) / int.Max(Geometry.SourceWidth, Geometry.SourceHeight));
var flowFrames = MotionBlur ? Plan.Frames.Count : Plan.Statistics.InterpolatedFrames;
return new ExportWorkload(Plan.Frames.Count, Plan.SlotCount, Plan.DurationSeconds, Geometry.OutputWidth, Geometry.OutputHeight, edge * shortEdge,
flowFrames, NeedsPreparation ? Plan.IncludedFrames.Count : 0, Encoder.Capability?.Hardware ?? false);
}
/// <summary>Size and time estimates for the values the encoder will actually use.</summary>
public ExportEstimate Estimate(ThroughputModel? model = null)
{
var s = Encoder.Settings;
return ExportEstimator.Estimate(Target.Export with { Codec = s.Codec, BitRate = s.BitRate, BitDepth = s.BitDepth, Quality = s.Quality }, Workload(), model);
}
}
@@ -0,0 +1,64 @@
namespace Titano.Core.Video.Managed;
/// <summary>
/// The encoders every platform has (BRIEF §11.3): MJPEG in AVI, JPEG / PNG (8 or 16-bit) / TIFF-16 / linear DNG image
/// sequences, animated GIF and APNG, all written by the in-house codecs. Frames are linear-light buffers at the output
/// size. Single files are written to a temporary sibling and renamed on <see cref="IVideoEncoderSession.Complete"/>;
/// sequences go to a temporary folder renamed the same way, so a cancelled or failed encode leaves nothing behind.
/// AVI and image sequences are constant frame rate: a frame lasting several periods is repeated.
/// </summary>
public sealed class ManagedEncoderProvider : IVideoEncoderProvider
{
public const string ProviderName = "managed";
/// <summary>Largest width or height of any managed output (JPEG, GIF and AVI headers use 16-bit sizes).</summary>
public const int MaxDimension = 65535;
public string Name => ProviderName;
public IReadOnlyList<EncoderCapability> Capabilities { get; } =
[
new(VideoCodec.Mjpeg, "Managed MJPEG", false, MaxDimension, MaxDimension, false),
new(VideoCodec.JpegSequence, "Managed JPEG sequence", false, MaxDimension, MaxDimension, false),
new(VideoCodec.PngSequence, "Managed PNG sequence", false, MaxDimension, MaxDimension, true),
new(VideoCodec.Tiff16Sequence, "Managed TIFF sequence", false, MaxDimension, MaxDimension, true),
new(VideoCodec.LinearDngSequence, "Managed linear DNG sequence", false, MaxDimension, MaxDimension, true),
new(VideoCodec.Gif, "Managed GIF", false, MaxDimension, MaxDimension, false),
new(VideoCodec.Apng, "Managed APNG", false, MaxDimension, MaxDimension, false),
];
/// <summary>Bit depths each managed codec writes.</summary>
public static IReadOnlyList<int> BitDepths(VideoCodec codec) => codec switch
{
VideoCodec.PngSequence => [8, 16],
VideoCodec.Tiff16Sequence => [16, 8],
VideoCodec.LinearDngSequence => [16],
VideoCodec.Mjpeg or VideoCodec.JpegSequence or VideoCodec.Gif or VideoCodec.Apng => [8],
_ => [],
};
public bool CanEncode(EncodeSettings settings) => Problem(settings) is null;
public IVideoEncoderSession Open(EncodeSettings settings)
{
ArgumentNullException.ThrowIfNull(settings);
if (Problem(settings) is { } problem) throw new NotSupportedException(problem);
var name = Capabilities.First(c => c.Codec == settings.Codec).Name;
return settings.Codec switch
{
VideoCodec.Mjpeg => new AviMjpegSession(settings, name),
VideoCodec.Gif => new GifSession(settings, name),
VideoCodec.Apng => new ApngSession(settings, name),
_ => new ImageSequenceSession(settings, name),
};
}
private static string? Problem(EncodeSettings s)
{
if (!VideoCodecInfo.IsManaged(s.Codec)) return $"{s.Codec} needs a platform encoder";
if (s.Width is <= 0 or > MaxDimension || s.Height is <= 0 or > MaxDimension) return $"{s.Width}×{s.Height} is outside 1–{MaxDimension}";
if (s.FrameRate.Numerator <= 0 || s.FrameRate.Denominator <= 0) return "The frame rate must be positive";
if (!BitDepths(s.Codec).Contains(s.BitDepth)) return $"{s.Codec} cannot be written with {s.BitDepth}-bit samples";
return string.IsNullOrWhiteSpace(s.OutputPath) ? "No output path" : null;
}
}
@@ -0,0 +1,301 @@
using System.IO.Compression;
using Titano.Core.Codecs.Apng;
using Titano.Core.Codecs.Dng;
using Titano.Core.Codecs.Gif;
using Titano.Core.Codecs.Jpeg;
using Titano.Core.Codecs.Png;
using Titano.Core.Codecs.Tiff;
using Titano.Core.Diagnostics;
using Titano.Core.Imaging;
using Titano.Core.IO;
using Titano.Core.Video.Avi;
namespace Titano.Core.Video.Managed;
/// <summary>Lifecycle shared by the managed sessions: validation, completion, and deletion of partial output on dispose.</summary>
internal abstract class ManagedSession(EncodeSettings settings, string encoderName) : IVideoEncoderSession
{
protected const string LogCategory = "ManagedEncoder";
private bool _completed;
private bool _disposed;
private int _frames;
public string EncoderName { get; } = encoderName;
public bool IsHardware => false;
protected EncodeSettings Settings { get; } = settings;
public void WriteFrame(ImageBuffer frame, long duration90k)
{
ArgumentNullException.ThrowIfNull(frame);
ObjectDisposedException.ThrowIf(_disposed, this);
if (_completed) throw new InvalidOperationException("The session is complete");
if (frame.Width != Settings.Width || frame.Height != Settings.Height) throw new ArgumentException("Frame size differs from the encode size", nameof(frame));
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(duration90k);
Write(frame, duration90k);
_frames++;
}
public void Complete()
{
ObjectDisposedException.ThrowIf(_disposed, this);
if (_completed) throw new InvalidOperationException("The session is already complete");
if (_frames == 0) throw new InvalidOperationException("No frames were written");
Commit();
_completed = true;
}
public void Dispose()
{
if (_disposed) return;
_disposed = true;
if (!_completed) Discard();
}
protected abstract void Write(ImageBuffer frame, long duration90k);
/// <summary>Finishes the container and moves it to <see cref="EncodeSettings.OutputPath"/>.</summary>
protected abstract void Commit();
/// <summary>Closes and deletes everything written so far.</summary>
protected abstract void Discard();
protected static JpegEncodeOptions JpegOptions(int quality) => new()
{
Quality = int.Clamp(quality, 1, 100),
Subsampling = quality >= 90 ? JpegSubsampling.Yuv444 : JpegSubsampling.Yuv420,
OptimizeHuffman = true,
};
}
/// <summary>Maps variable frame durations onto a constant-rate grid: a frame is repeated for every period it covers
/// (rounded on the cumulative timeline, so the total stays exact).</summary>
internal sealed class ConstantRateClock(Rational frameRate)
{
private long _ticks;
private long _periods;
/// <summary>Periods the next frame of <paramref name="duration90k"/> ticks occupies (0 when it is shorter than the grid allows).</summary>
public int Advance(long duration90k)
{
_ticks += duration90k;
var end = (_ticks * frameRate.Numerator * 2 + 90000L * frameRate.Denominator) / (2 * 90000L * frameRate.Denominator);
var periods = (int)(end - _periods);
_periods = end;
return periods;
}
}
/// <summary>A single output file written to a temporary sibling and renamed into place.</summary>
internal abstract class SingleFileSession : ManagedSession
{
private readonly string _tempPath;
protected SingleFileSession(EncodeSettings settings, string encoderName) : base(settings, encoderName)
{
_tempPath = AtomicFile.TempPathFor(settings.OutputPath);
File = new FileStream(_tempPath, FileMode.CreateNew, FileAccess.ReadWrite, FileShare.None, 1 << 20);
}
protected FileStream File { get; }
protected abstract void Finish();
protected override void Commit()
{
Finish();
File.Flush(flushToDisk: true);
File.Dispose();
AtomicFile.Commit(_tempPath, Settings.OutputPath);
}
protected override void Discard()
{
File.Dispose();
try
{
System.IO.File.Delete(_tempPath);
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
Log.Warning(LogCategory, "Could not delete the partial output " + _tempPath, ex);
}
}
}
internal sealed class AviMjpegSession : SingleFileSession
{
private readonly AviMjpegWriter _writer;
private readonly ConstantRateClock _clock;
private readonly JpegEncodeOptions _jpeg;
public AviMjpegSession(EncodeSettings settings, string encoderName) : base(settings, encoderName)
{
try
{
_writer = new AviMjpegWriter(File, settings.Width, settings.Height, settings.FrameRate);
}
catch
{
Discard();
throw;
}
_clock = new ConstantRateClock(settings.FrameRate);
_jpeg = JpegOptions(settings.Quality);
}
protected override void Write(ImageBuffer frame, long duration90k)
{
var repeats = _clock.Advance(duration90k);
if (repeats == 0) return;
var jpeg = JpegEncoder.Encode(frame, _jpeg);
for (var i = 0; i < repeats; i++) _writer.WriteFrame(jpeg);
}
protected override void Finish() => _writer.Complete();
}
internal sealed class GifSession : SingleFileSession
{
private readonly GifEncoder _encoder;
public GifSession(EncodeSettings settings, string encoderName) : base(settings, encoderName)
{
try
{
_encoder = new GifEncoder(File, settings.Width, settings.Height);
}
catch
{
Discard();
throw;
}
}
protected override void Write(ImageBuffer frame, long duration90k) => _encoder.AddFrame(frame, duration90k);
protected override void Finish() => _encoder.Complete();
}
internal sealed class ApngSession : SingleFileSession
{
private readonly ApngEncoder _encoder;
public ApngSession(EncodeSettings settings, string encoderName) : base(settings, encoderName)
{
try
{
_encoder = new ApngEncoder(File, settings.Width, settings.Height, new ApngEncoderOptions { CompressionLevel = CompressionLevel.Optimal });
}
catch
{
Discard();
throw;
}
}
protected override void Write(ImageBuffer frame, long duration90k) => _encoder.AddFrame(frame, duration90k);
protected override void Finish() => _encoder.Complete();
}
/// <summary>
/// Numbered image files (<c>&lt;folder name&gt;_000001.ext</c>, 1-based, six digits) in the output folder. Files are written
/// (and flushed) into a hidden temporary sibling folder that is renamed to the output folder on completion. Frames are
/// independent, so several are encoded at once (each single-threaded, at most one per core): PNG's Deflate would
/// otherwise run on one core. A failed encode surfaces on a later <see cref="IVideoEncoderSession.WriteFrame"/> or on
/// <see cref="IVideoEncoderSession.Complete"/>.
/// </summary>
internal sealed class ImageSequenceSession : ManagedSession
{
private readonly string _folder;
private readonly string _temp;
private readonly string _stem;
private readonly string _extension;
private readonly ConstantRateClock _clock;
private readonly Queue<Task> _inFlight = new();
private readonly int _maxInFlight = int.Clamp(Environment.ProcessorCount, 1, 8);
private int _index;
public ImageSequenceSession(EncodeSettings settings, string encoderName) : base(settings, encoderName)
{
_folder = Path.GetFullPath(settings.OutputPath).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
if (Directory.Exists(_folder) || System.IO.File.Exists(_folder)) throw new IOException($"The output \"{_folder}\" already exists");
var parent = Path.GetDirectoryName(_folder) ?? throw new ArgumentException("The output folder needs a parent", nameof(settings));
_stem = Path.GetFileName(_folder);
_extension = VideoCodecInfo.FileExtension(settings.Codec);
Directory.CreateDirectory(parent);
_temp = Path.Combine(parent, "." + _stem + "." + Guid.NewGuid().ToString("N")[..8] + ".tmp");
Directory.CreateDirectory(_temp);
_clock = new ConstantRateClock(settings.FrameRate);
}
/// <summary>File name of the 1-based frame <paramref name="number"/> inside a sequence folder named <paramref name="stem"/>.</summary>
public static string FrameName(string stem, int number, string extension) =>
string.Create(System.Globalization.CultureInfo.InvariantCulture, $"{stem}_{number:D6}{extension}");
protected override void Write(ImageBuffer frame, long duration90k)
{
var repeats = _clock.Advance(duration90k);
if (repeats == 0) return;
while (_inFlight.Count >= _maxInFlight) _inFlight.Dequeue().GetAwaiter().GetResult();
var first = _index + 1;
_index += repeats;
var copy = frame.Clone();
_inFlight.Enqueue(Task.Run(() =>
{
byte[] bytes;
using (copy) bytes = Encode(copy);
for (var number = first; number < first + repeats; number++)
{
using var file = new FileStream(Path.Combine(_temp, FrameName(_stem, number, _extension)), FileMode.CreateNew, FileAccess.Write, FileShare.None, 1 << 16);
file.Write(bytes);
file.Flush(flushToDisk: true);
}
}));
}
protected override void Commit()
{
while (_inFlight.Count > 0) _inFlight.Dequeue().GetAwaiter().GetResult();
Directory.Move(_temp, _folder);
}
protected override void Discard()
{
// Every encode must have stopped writing before the folder goes; their failures are already superseded.
while (_inFlight.Count > 0)
{
try
{
_inFlight.Dequeue().GetAwaiter().GetResult();
}
catch (Exception ex)
{
Log.Warning(LogCategory, "A sequence frame failed while the encode was being discarded", ex);
}
}
try
{
Directory.Delete(_temp, recursive: true);
}
catch (Exception ex) when (ex is IOException or UnauthorizedAccessException)
{
Log.Warning(LogCategory, "Could not delete the partial sequence " + _temp, ex);
}
}
/// <summary>One frame, single-threaded (frames are encoded concurrently).</summary>
private byte[] Encode(ImageBuffer frame) => Settings.Codec switch
{
VideoCodec.JpegSequence => JpegEncoder.Encode(frame, JpegOptions(Settings.Quality) with { MaxDegreeOfParallelism = 1 }),
VideoCodec.PngSequence => PngEncoder.Encode(frame, Settings.BitDepth == 16 ? 16 : 8, CompressionLevel.Optimal),
VideoCodec.Tiff16Sequence => TiffWriter.Write(frame, new TiffWriteOptions { BitsPerSample = Settings.BitDepth == 8 ? 8 : 16, MaxDegreeOfParallelism = 1 }),
// Tiles no larger than the frame: edge padding of a 256-pixel tile would dominate small outputs.
VideoCodec.LinearDngSequence => LinearDngWriter.Write(frame,
new LinearDngOptions { TileSize = int.Clamp((int.Max(frame.Width, frame.Height) + 15) / 16 * 16, 16, 256), MaxDegreeOfParallelism = 1 }),
_ => throw new NotSupportedException($"{Settings.Codec} is not an image sequence"),
};
}
@@ -0,0 +1,79 @@
using System.Diagnostics;
using System.Globalization;
using Titano.Core.Diagnostics;
using Titano.Core.Render.Diagnostics;
namespace Titano.Tools.Commands;
/// <summary>
/// <c>selftest [prefix…] [--filter prefix] [--list]</c>: the engine's end-to-end self-test (BRIEF §20.2, §20.4) with
/// the managed encoders. Prints a PASS/FAIL table; exits 1 when a check fails, 2 when no check matched.
/// </summary>
internal sealed class SelfTestCommand : ICommand
{
public string Name => "selftest";
public string Summary => "Render synthetic sequences end to end and verify the outputs";
public async Task<int> RunAsync(string[] args)
{
var a = new Args(args, "list");
var filters = a.Positional.ToList();
if (a.Get("filter") is { } filter) filters.Add(filter);
if (a.Has("list"))
{
foreach (var check in SelfTest.Checks) Console.WriteLine($"{check.Id,-26} {check.Description}");
return 0;
}
using var cts = new CancellationTokenSource();
ConsoleCancelEventHandler cancel = (_, e) =>
{
e.Cancel = true;
cts.Cancel();
};
Console.CancelKeyPress += cancel;
// Expected failures (fault injection, render-node notices) are logged by the engine; the table says enough.
var level = Log.MinimumLevel;
Log.MinimumLevel = LogLevel.Error;
try
{
var clock = Stopwatch.StartNew();
Console.WriteLine($"{"RESULT",-6} {"CHECK",-26} {"TIME",8} DETAIL");
var results = await SelfTest.RunAsync(new SelfTestOptions { Filters = filters }, new ConsoleRows(), cts.Token);
var passed = results.Count(r => r.Outcome == SelfTestOutcome.Passed);
var failed = results.Count(r => r.Outcome == SelfTestOutcome.Failed);
var skipped = results.Count(r => r.Outcome == SelfTestOutcome.Skipped);
Console.WriteLine(string.Create(CultureInfo.InvariantCulture,
$"{(failed == 0 ? "PASSED" : "FAILED")} {results.Count} checks: {passed} passed, {failed} failed, {skipped} skipped in {clock.Elapsed.TotalSeconds:F1} s"));
if (results.Count == 0) return 2;
return failed == 0 ? 0 : 1;
}
catch (OperationCanceledException) when (cts.IsCancellationRequested)
{
Console.Error.WriteLine("Self-test cancelled.");
return 2;
}
finally
{
Log.MinimumLevel = level;
Console.CancelKeyPress -= cancel;
}
}
/// <summary>Prints each result as soon as its check finishes.</summary>
private sealed class ConsoleRows : IProgress<SelfTestResult>
{
public void Report(SelfTestResult r)
{
var label = r.Outcome switch
{
SelfTestOutcome.Passed => "PASS",
SelfTestOutcome.Failed => "FAIL",
_ => "SKIP",
};
var line = string.Create(CultureInfo.InvariantCulture, $"{label,-6} {r.Id,-26} {r.Elapsed.TotalMilliseconds,6:F0} ms {r.Detail}");
if (r.Outcome == SelfTestOutcome.Failed) Console.Error.WriteLine(line);
else Console.WriteLine(line);
}
}
}
+1
View File
@@ -9,6 +9,7 @@ var commands = new ICommand[]
new PackageGuardCommand(),
new ChangelogCommand(),
new PackInstallerCommand(),
new SelfTestCommand(),
};
if (args.Length == 0 || args[0] is "-h" or "--help" or "help")
@@ -0,0 +1,146 @@
using Titano.Core.Export;
using Titano.Core.Tests.Render;
using Titano.Core.Video;
using Titano.Core.Video.Managed;
using Titano.Testing;
namespace Titano.Core.Tests.Export;
public sealed class EncoderSelectorTests
{
private static readonly EncoderCapability SoftwareH264 = new(VideoCodec.H264, "Microsoft H.264", false, 4096, 2304, false);
private static readonly EncoderCapability HardwareH264 = new(VideoCodec.H264, "NVENC H.264", true, 4096, 4096, false, "NVIDIA");
private static readonly EncoderCapability HardwareHevc = new(VideoCodec.Hevc, "NVENC HEVC", true, 8192, 8192, true, "NVIDIA");
private static readonly EncoderCapability HardwareHevc8 = new(VideoCodec.Hevc, "QSV HEVC", true, 8192, 8192, false, "Intel");
private static EncodeSettings Request(VideoCodec codec, int width = 3840, int height = 2160, int bitDepth = 8, long bitRate = 20_000_000, Rational? fps = null) => new()
{
OutputPath = "/exports/out" + VideoCodecInfo.FileExtension(codec),
Codec = codec,
Width = width,
Height = height,
FrameRate = fps ?? new Rational(30, 1),
BitDepth = bitDepth,
BitRate = bitRate,
Profile = bitDepth == 10 ? CodecProfile.HevcMain10 : CodecProfile.Auto,
};
private static IVideoEncoderProvider[] Client(params EncoderCapability[] capabilities) =>
[new CapturingEncoderProvider("Media Foundation", capabilities), new ManagedEncoderProvider()];
[Test]
public void ManagedCodecsUseTheManagedProviderEverywhere()
{
foreach (var host in new[] { EncoderHost.Client, EncoderHost.Server })
{
var selection = EncoderSelector.Select(Request(VideoCodec.Mjpeg, bitDepth: 8), Client(HardwareH264), host);
Assert.True(selection.IsReady);
Assert.Equal(ManagedEncoderProvider.ProviderName, selection.Provider!.Name);
Assert.Equal("Managed MJPEG", selection.Capability!.Name);
Assert.Empty(selection.Notices);
}
}
[Test]
public void ManagedBitDepthsAreAdjustedWithANotice()
{
var png = EncoderSelector.Select(Request(VideoCodec.PngSequence, bitDepth: 10), [new ManagedEncoderProvider()], EncoderHost.Server);
Assert.Equal(16, png.Settings.BitDepth);
Assert.Equal(EncoderNotices.BitDepthAdjusted, png.Notices.Single().Key);
Assert.SequenceEqual(new[] { "10", "16" }, png.Notices.Single().Args);
var jpeg = EncoderSelector.Select(Request(VideoCodec.JpegSequence, bitDepth: 16), [new ManagedEncoderProvider()], EncoderHost.Server);
Assert.Equal(8, jpeg.Settings.BitDepth);
}
[Test]
public void ServerNeedsARenderNodeForMp4()
{
var selection = EncoderSelector.Select(Request(VideoCodec.H264), [new ManagedEncoderProvider()], EncoderHost.Server);
Assert.Equal(EncoderSelectionStatus.NeedsRenderNode, selection.Status);
Assert.Null(selection.Provider);
Assert.Equal(EncoderNotices.NeedsRenderNode, selection.Notices.Single().Key);
Assert.Throws<InvalidOperationException>(() => selection.Open());
}
[Test]
public void HardwareIsPreferredUnlessSoftwareIsAsked()
{
var providers = Client(SoftwareH264, HardwareH264);
var hardware = EncoderSelector.Select(Request(VideoCodec.H264), providers, EncoderHost.Client);
Assert.True(hardware.IsReady);
Assert.Equal("NVENC H.264", hardware.Capability!.Name);
Assert.Empty(hardware.Notices);
Assert.Equal(new CodecLevel(VideoCodec.H264, 5, 1), hardware.Level);
var software = EncoderSelector.Select(Request(VideoCodec.H264) with { PreferHardware = false }, providers, EncoderHost.Client);
Assert.Equal("Microsoft H.264", software.Capability!.Name);
var named = EncoderSelector.Select(Request(VideoCodec.H264) with { EncoderName = "Microsoft H.264" }, providers, EncoderHost.Client);
Assert.Equal("Microsoft H.264", named.Capability!.Name);
Assert.Equal(EncoderNotices.SoftwareOnly, named.Notices.Single().Key);
}
[Test]
public void HevcFallsBackToH264WhenNoEncoderExists()
{
var selection = EncoderSelector.Select(Request(VideoCodec.Hevc, bitDepth: 10, bitRate: 14_000_000), Client(SoftwareH264), EncoderHost.Client);
Assert.True(selection.IsReady);
Assert.Equal(VideoCodec.H264, selection.Settings.Codec);
Assert.Equal(8, selection.Settings.BitDepth);
Assert.Equal(CodecProfile.H264High, selection.Settings.Profile);
Assert.Equal(20_000_000L, selection.Settings.BitRate);
Assert.Equal(EncoderNotices.FallbackToH264, selection.Notices[0].Key);
Assert.SequenceEqual(new[] { "Hevc" }, selection.Notices[0].Args);
Assert.Contains(selection.Notices, n => n.Key == EncoderNotices.SoftwareOnly);
Assert.Equal(".mp4", Path.GetExtension(selection.Settings.OutputPath));
}
[Test]
public void TenBitNeedsATenBitEncoder()
{
var eightOnly = EncoderSelector.Select(Request(VideoCodec.Hevc, bitDepth: 10), Client(HardwareHevc8), EncoderHost.Client);
Assert.Equal(8, eightOnly.Settings.BitDepth);
Assert.Equal(CodecProfile.HevcMain, eightOnly.Settings.Profile);
Assert.Equal(EncoderNotices.TenBitUnavailable, eightOnly.Notices.Single().Key);
var tenBit = EncoderSelector.Select(Request(VideoCodec.Hevc, bitDepth: 10), Client(HardwareHevc8, HardwareHevc), EncoderHost.Client);
Assert.Equal("NVENC HEVC", tenBit.Capability!.Name);
Assert.Equal(10, tenBit.Settings.BitDepth);
Assert.Empty(tenBit.Notices);
}
[Test]
public void SizeIsCappedByEncoderAndLevel()
{
var encoder = EncoderSelector.Select(Request(VideoCodec.H264, 7680, 4320), Client(HardwareH264), EncoderHost.Client);
Assert.Equal((4096, 2304), (encoder.Settings.Width, encoder.Settings.Height));
Assert.Equal(EncoderNotices.ResolutionCappedByEncoder, encoder.Notices.Single().Key);
Assert.SequenceEqual(new[] { "NVENC H.264", "4096×2304" }, encoder.Notices.Single().Args);
var level = EncoderSelector.Select(Request(VideoCodec.Hevc, 7680, 4320, fps: new Rational(240, 1)), Client(HardwareHevc), EncoderHost.Client);
Assert.Equal(EncoderNotices.ResolutionCappedByLevel, level.Notices[0].Key);
Assert.Less(level.Settings.Width, 7680);
Assert.Equal(0, level.Settings.Width % 2);
Assert.Approximately(16.0 / 9, level.Settings.Width / (double)level.Settings.Height, 0.01);
Assert.True(CodecLimits.Check(VideoCodec.Hevc, level.Settings.Width, level.Settings.Height, 240, level.Settings.BitRate).Fits);
var odd = EncoderSelector.Select(Request(VideoCodec.H264, 1081, 607), Client(HardwareH264), EncoderHost.Client);
Assert.Equal((1080, 606), (odd.Settings.Width, odd.Settings.Height));
}
[Test]
public void BitRateIsCappedByTheHighestLevel()
{
var selection = EncoderSelector.Select(Request(VideoCodec.H264, 1920, 1080, bitRate: 2_000_000_000), Client(HardwareH264), EncoderHost.Client);
Assert.Equal(1_000_000_000L, selection.Settings.BitRate);
Assert.Equal(EncoderNotices.BitRateCapped, selection.Notices.Single().Key);
}
[Test]
public void NoVideoEncoderMeansUnavailable()
{
var selection = EncoderSelector.Select(Request(VideoCodec.Av1), [new ManagedEncoderProvider()], EncoderHost.Client);
Assert.Equal(EncoderSelectionStatus.Unavailable, selection.Status);
Assert.SequenceEqual(new[] { EncoderNotices.FallbackToH264, EncoderNotices.NoEncoder }, selection.Notices.Select(n => n.Key));
}
}
@@ -0,0 +1,61 @@
using Titano.Core.Export;
using Titano.Core.Video;
using Titano.Testing;
namespace Titano.Core.Tests.Export;
public sealed class ExportEstimateTests
{
private static ExportWorkload Workload(int frames = 600, int width = 3840, int height = 2160, int flow = 0, int analysis = 0, bool hardware = true) =>
new(frames, frames, frames / 24.0, width, height, (long)width * height, flow, analysis, hardware);
private static ResolvedExport Preset(string id) => ExportResolver.FromPreset(ExportPresets.Find(id)!);
[Test]
public void VideoSizeIsBitRateTimesDuration()
{
var export = Preset("4k-h264");
var bytes = ExportEstimator.EstimateBytes(export, Workload());
var expected = 0.10 * 3840 * 2160 * 24 * 25 / 8 * 1.01;
Assert.Approximately(expected, bytes, 1);
Assert.InRange(bytes / 1e6, 60, 70); // ≈ 63 MB for 25 s of 4K at 19.9 Mb/s
}
[Test]
public void FrameBasedSizesScaleWithPicturesAndDepth()
{
var png8 = ExportResolver.FromPreset(ExportPresets.Find("png-sequence")!) with { Width = 1920, Height = 1080 };
var png16 = png8 with { BitDepth = 16 };
var w = Workload(240, 1920, 1080) with { OutputPeriods = 480 };
Assert.Equal(2 * ExportEstimator.EstimateBytes(png8, Workload(240, 1920, 1080)), ExportEstimator.EstimateBytes(png8, w));
Assert.Greater(ExportEstimator.EstimateBytes(png16, w), 2 * ExportEstimator.EstimateBytes(png8, w));
var gif = Preset("gif-preview");
Assert.Less(ExportEstimator.EstimateBytes(gif, Workload(240, 480, 270)), ExportEstimator.EstimateBytes(Preset("apng"), Workload(240, 480, 270)));
Assert.Monotonic(Enumerable.Range(1, 100).Select(q => ExportEstimator.JpegBitsPerPixel(q)), strict: true);
Assert.Approximately(2.8, ExportEstimator.JpegBitsPerPixel(90), 1e-12);
var mjpeg = Preset("mjpeg-avi");
Assert.Greater(ExportEstimator.EstimateBytes(mjpeg, Workload()), ExportEstimator.EstimateBytes(Preset("4k-hevc10-archive"), Workload()));
}
[Test]
public void TimeGrowsWithWorkAndCalibrationRescalesIt()
{
var export = Preset("4k-hevc");
var model = ThroughputModel.Default;
var plain = ExportEstimator.EstimateTime(export.Codec, Workload(), model);
Assert.Greater(ExportEstimator.EstimateTime(export.Codec, Workload(flow: 600), model).TotalSeconds, 2 * plain.TotalSeconds);
Assert.Greater(ExportEstimator.EstimateTime(export.Codec, Workload(analysis: 600), model).TotalSeconds, plain.TotalSeconds);
Assert.Greater(ExportEstimator.EstimateTime(export.Codec, Workload(hardware: false), model).TotalSeconds, plain.TotalSeconds);
Assert.InRange(plain.TotalSeconds, 30, 600); // ≈ 4 frames per second of 4K on the default model
var faster = model.Calibrate(plain, plain / 2, weight: 1);
Assert.Approximately(2.0, faster.Scale, 1e-9);
Assert.Approximately(plain.TotalSeconds / 2, ExportEstimator.EstimateTime(export.Codec, Workload(), faster).TotalSeconds, 1e-6);
Assert.Approximately(Math.Sqrt(2), model.Calibrate(plain, plain / 2).Scale, 1e-9);
Assert.Same(model, model.Calibrate(TimeSpan.Zero, plain));
var estimate = ExportEstimator.Estimate(export, Workload());
Assert.Equal(ExportEstimator.EstimateBytes(export, Workload()), estimate.Bytes);
Assert.Equal(plain, estimate.Time);
}
}
@@ -0,0 +1,83 @@
using Titano.Core.Export;
using Titano.Core.Project;
using Titano.Core.Video;
using Titano.Testing;
namespace Titano.Core.Tests.Export;
public sealed class ExportNamingTests
{
private readonly TestContext _context;
public ExportNamingTests(TestContext context) => _context = context;
private static ExportNameContext Context(VideoCodec codec = VideoCodec.Hevc, string? title = "Harbour sunset") => new()
{
Date = new DateTime(2024, 6, 21, 19, 30, 0),
Title = title,
PresetName = "4K UHD HEVC",
Width = 3840,
Height = 2160,
FrameRate = Rational.Fps2997,
Codec = codec,
};
[Test]
public void DefaultTemplateNamesTheRender()
{
var name = ExportNaming.Expand("{date} {title} - {preset}", Context());
Assert.Equal("2024-06-21 Harbour sunset - 4K UHD HEVC", name.Name);
Assert.True(name.IsValid);
}
[Test]
public void EveryTokenExpands()
{
var name = ExportNaming.Expand("{date:yyyyMMdd}_{width}x{height}_{fps}fps_{codec}_{{raw}}", Context());
Assert.Equal("20240621_3840x2160_29.97fps_HEVC_{raw}", name.Name);
Assert.Equal("PNG", ExportNaming.CodecLabel(VideoCodec.PngSequence));
Assert.Equal("H.264", ExportNaming.CodecLabel(VideoCodec.H264));
}
[Test]
public void IllegalCharactersAndProblemsAreReported()
{
var name = ExportNaming.Expand("{title} {bogus} {", Context(title: "a/b:c*d?"));
Assert.Equal("a-b_c_d_ {", name.Name);
Assert.Count(2, name.Errors);
Assert.Equal("UnknownToken", name.Errors[0].Code);
Assert.Equal("UnclosedBrace", name.Errors[1].Code);
Assert.Equal(ExportNaming.FallbackName, ExportNaming.Expand("{title}", Context(title: null)).Name);
Assert.Equal("2024-06-21 - 4K UHD HEVC", ExportNaming.Expand("{date} {title} - {preset}", Context(title: null)).Name);
}
[Test]
public void CollisionsGetANumberedSuffix()
{
var dir = _context.CreateTempDirectory();
var first = ExportNaming.OutputPath(dir, "{title}", Context());
Assert.Equal(Path.Combine(dir, "Harbour sunset.mp4"), first);
File.WriteAllBytes(first, [1]);
var second = ExportNaming.OutputPath(dir, "{title}", Context());
Assert.Equal(Path.Combine(dir, "Harbour sunset (2).mp4"), second);
File.WriteAllBytes(second, [1]);
Assert.Equal(Path.Combine(dir, "Harbour sunset (3).mp4"), ExportNaming.OutputPath(dir, "{title}", Context()));
var sequence = ExportNaming.OutputPath(dir, "{title}", Context(VideoCodec.PngSequence));
Assert.Equal(Path.Combine(dir, "Harbour sunset"), sequence);
Directory.CreateDirectory(sequence);
Assert.Equal(Path.Combine(dir, "Harbour sunset (2)"), ExportNaming.OutputPath(dir, "{title}", Context(VideoCodec.PngSequence)));
Assert.Equal(Path.Combine(dir, "Harbour sunset.gif"), ExportNaming.OutputPath(dir, "{title}", Context(VideoCodec.Gif)));
}
[Test]
public void ProjectSettingsChooseFolderAndTemplate()
{
var exports = _context.CreateTempDirectory("exports");
var custom = _context.CreateTempDirectory("custom");
var byDefault = ExportNaming.OutputPath(new ExportSettings(), exports, Context());
Assert.Equal(Path.Combine(exports, "2024-06-21 Harbour sunset - 4K UHD HEVC.mp4"), byDefault);
var chosen = ExportNaming.OutputPath(new ExportSettings { Folder = custom, NameTemplate = "{title} {width}" }, exports, Context());
Assert.Equal(Path.Combine(custom, "Harbour sunset 3840.mp4"), chosen);
}
}
@@ -0,0 +1,131 @@
using Titano.Core.Export;
using Titano.Core.Project;
using Titano.Core.Video;
using Titano.Testing;
namespace Titano.Core.Tests.Export;
public sealed class ExportResolverTests
{
private static ExportSettings Export(string preset, ExportOverrides? overrides = null) =>
new() { Preset = new Auto<string>().WithManual(preset), Overrides = overrides ?? new ExportOverrides() };
[Test]
public void EveryBuiltInPresetResolvesToItself()
{
foreach (var preset in ExportPresets.BuiltIn)
{
var resolved = ExportResolver.Resolve(Export(preset.Id));
Assert.Equal(preset.Id, resolved.PresetId);
Assert.False(resolved.IsCustom);
Assert.Equal(preset.NameKey, resolved.NameKey);
Assert.Equal(preset.Codec, resolved.Codec);
Assert.Empty(resolved.Warnings);
}
}
[Test]
public void EditingAValueMakesTheExportCustom()
{
var resolved = ExportResolver.Resolve(Export("4k-hevc", new ExportOverrides { BitRate = 50_000_000 }));
Assert.True(resolved.IsCustom);
Assert.Equal(ExportResolver.CustomId, resolved.PresetId);
Assert.Equal("4k-hevc", resolved.BasePresetId);
Assert.Null(resolved.NameKey);
Assert.Equal(50_000_000L, resolved.EffectiveBitRate(3840, 2160));
Assert.Equal(3840, resolved.Width);
}
[Test]
public void ValuesEqualToThePresetRestoreItsName()
{
var resolved = ExportResolver.Resolve(Export("1080p-h264", new ExportOverrides
{
Codec = "h.264",
Container = "mp4",
Width = 1920,
Height = 1080,
FrameRate = "30",
BitRate = 6_220_800, // the preset's 0.10 bpp at 1920×1080×30
GopFrames = 30,
Profile = "H264High",
RateControl = "vbr",
}));
Assert.Equal("1080p-h264", resolved.PresetId);
Assert.Empty(resolved.Warnings);
}
[Test]
public void ValuesEqualToAnotherPresetTakeItsName()
{
var resolved = ExportResolver.Resolve(Export("1080p-h264", new ExportOverrides { FrameRate = "60" }));
Assert.Equal("1080p60", resolved.PresetId);
Assert.Equal(60, resolved.GopFrames);
Assert.Equal("1080p-h264", resolved.BasePresetId);
}
[Test]
public void FractionalRatesAndGopFollowTheOverride()
{
var resolved = ExportResolver.Resolve(Export("4k-h264", new ExportOverrides { FrameRate = "24000/1001" }));
Assert.True(resolved.IsCustom);
Assert.Equal(Rational.Fps23976, resolved.FrameRate);
Assert.Equal(24, resolved.GopFrames);
var settings = resolved.ToEncodeSettings("x.mp4", 3840, 2160);
Assert.Equal(24, settings.GopLength);
Assert.Equal((long)Math.Round(0.10 * 3840 * 2160 * 24000 / 1001.0), settings.BitRate);
Assert.Equal(CodecProfile.H264High, settings.Profile);
}
[Test]
public void BadOverridesAreIgnoredWithWarnings()
{
var resolved = ExportResolver.Resolve(Export("1080p-h264", new ExportOverrides { Codec = "divx", FrameRate = "fast", Container = "avi", Profile = "ultra", RateControl = "magic" }));
Assert.Equal("1080p-h264", resolved.PresetId);
Assert.SequenceEqual(new[] { "Export.Warning.UnknownCodec", "Export.Warning.ContainerIgnored", "Export.Warning.UnknownProfile", "Export.Warning.UnknownFrameRate", "Export.Warning.UnknownRateControl" }, resolved.Warnings);
}
[Test]
public void UnknownOrCustomSelectionsStartFromTheDefaultPreset()
{
var unknown = ExportResolver.Resolve(Export("deleted-user-preset"));
Assert.Equal(ExportResolver.DefaultPresetId, unknown.PresetId);
Assert.Contains("Export.Warning.UnknownPreset", unknown.Warnings);
var custom = ExportResolver.Resolve(Export("custom", new ExportOverrides { Codec = "png", Width = 0, Height = 0, BitDepth = 16, FrameRate = "30", GopFrames = 30, BFrames = 0, Quality = 92 }));
Assert.Empty(custom.Warnings);
Assert.Equal(VideoCodec.PngSequence, custom.Codec);
Assert.True(custom.IsCustom);
var auto = ExportResolver.Resolve(new ExportSettings());
Assert.Equal(ExportResolver.DefaultPresetId, auto.PresetId);
}
[Test]
public void ChangingTheCodecResetsCodecSpecificValues()
{
var resolved = ExportResolver.Resolve(Export("1080p-h264", new ExportOverrides { Codec = "HEVC" }));
Assert.Equal(VideoCodec.Hevc, resolved.Codec);
Assert.Equal(CodecProfile.Auto, resolved.Profile);
Assert.Equal((long)Math.Round(0.07 * 1920 * 1080 * 30), resolved.EffectiveBitRate(1920, 1080));
Assert.True(resolved.IsCustom);
Assert.True(ExportResolver.TryParseCodec("TIFF-16", out var tiff) && tiff == VideoCodec.Tiff16Sequence);
Assert.False(ExportResolver.TryParseCodec("", out _));
}
[Test]
public void FrameRateTextRoundTrips()
{
Assert.True(FrameRateText.TryParse("30000/1001", out var ntsc));
Assert.Equal(Rational.Fps2997, ntsc);
Assert.True(FrameRateText.TryParse("29.97", out var decimalNtsc));
Assert.Equal(Rational.Fps2997, decimalNtsc);
Assert.True(FrameRateText.TryParse(" 25 ", out var pal));
Assert.Equal("25", FrameRateText.Format(pal));
Assert.Equal("24000/1001", FrameRateText.Format(Rational.Fps23976));
Assert.True(FrameRateText.AreEqual(new Rational(48000, 2002), Rational.Fps23976));
Assert.False(FrameRateText.TryParse("0", out _));
Assert.False(FrameRateText.TryParse("1/0", out _));
Assert.False(FrameRateText.TryParse(null, out _));
}
}
@@ -0,0 +1,213 @@
using Titano.Core.Codecs.Jpeg;
using Titano.Core.Codecs.Png;
using Titano.Core.Codecs.Tiff;
using Titano.Core.Imaging;
using Titano.Core.Render.Diagnostics;
using Titano.Core.Video;
using Titano.Core.Video.Managed;
using Titano.Testing;
namespace Titano.Core.Tests.Export;
public sealed class ManagedEncoderTests
{
private const int Width = 48;
private const int Height = 32;
private static readonly Rational Fps = new(30, 1);
private readonly TestContext _context;
public ManagedEncoderTests(TestContext context) => _context = context;
private static ImageBuffer Frame(int seed)
{
var image = new ImageBuffer(Width, Height);
for (var y = 0; y < Height; y++)
{
for (var x = 0; x < Width; x++)
{
image[0, x, y] = (x + seed * 7) % Width / (float)Width;
image[1, x, y] = y / (float)Height * 0.8f;
image[2, x, y] = (x * y + seed * 13) % 23 / 22f * 0.5f;
}
}
return image;
}
private static EncodeSettings Settings(string path, VideoCodec codec, int bitDepth = 8) =>
new() { OutputPath = path, Codec = codec, Width = Width, Height = Height, FrameRate = Fps, BitDepth = bitDepth, Quality = 95 };
/// <summary>Three distinct frames lasting one, two and one periods.</summary>
private static void Encode(IVideoEncoderSession session)
{
long[] durations = [3000, 6000, 3000];
for (var i = 0; i < 3; i++)
{
using var frame = Frame(i);
session.WriteFrame(frame, durations[i]);
}
session.Complete();
}
private static double Psnr(ImageBuffer expected, ImageBuffer actual)
{
var a = PixelConvert.ToInterleaved8(expected, 3);
var b = PixelConvert.ToInterleaved8(actual, 3);
double sum = 0;
for (var i = 0; i < a.Length; i++) sum += (a[i] - b[i]) * (a[i] - b[i]);
return sum == 0 ? double.PositiveInfinity : 10 * Math.Log10(255.0 * 255 / (sum / a.Length));
}
[Test]
public void MjpegAviRepeatsHeldFramesOnTheConstantRateGrid()
{
var dir = _context.CreateTempDirectory();
var path = Path.Combine(dir, "out.avi");
using (var session = new ManagedEncoderProvider().Open(Settings(path, VideoCodec.Mjpeg))) Encode(session);
var avi = AviReader.Read(File.ReadAllBytes(path));
Assert.Equal(4, avi.Frames.Count);
Assert.Equal(4, avi.HeaderFrames);
Assert.Equal(4, avi.IndexEntries);
Assert.Equal(Fps, avi.FrameRate);
Assert.BytesEqual(avi.Frames[1], avi.Frames[2]);
using var decoded = JpegDecoder.DecodeToLinear(avi.Frames[3]);
using var expected = Frame(2);
Assert.Greater(Psnr(expected, decoded), 35);
Assert.SequenceEqual(new[] { "out.avi" }, Directory.GetFiles(dir).Select(Path.GetFileName));
}
[Theory]
[Case(VideoCodec.JpegSequence, 8)]
[Case(VideoCodec.PngSequence, 8)]
[Case(VideoCodec.PngSequence, 16)]
[Case(VideoCodec.Tiff16Sequence, 16)]
[Case(VideoCodec.LinearDngSequence, 16)]
public void SequencesWriteNumberedFilesIntoTheOutputFolder(VideoCodec codec, int bitDepth)
{
var dir = _context.CreateTempDirectory();
var folder = Path.Combine(dir, "Harbour - sequence");
using (var session = new ManagedEncoderProvider().Open(Settings(folder, codec, bitDepth))) Encode(session);
Assert.SequenceEqual(new[] { "Harbour - sequence" }, Directory.GetFileSystemEntries(dir).Select(Path.GetFileName));
var ext = VideoCodecInfo.FileExtension(codec);
var files = Directory.GetFiles(folder).Order(StringComparer.Ordinal).ToArray();
Assert.SequenceEqual(Enumerable.Range(1, 4).Select(i => $"Harbour - sequence_{i:D6}{ext}"), files.Select(Path.GetFileName));
Assert.BytesEqual(File.ReadAllBytes(files[1]), File.ReadAllBytes(files[2]));
using var expected = Frame(2);
var bytes = File.ReadAllBytes(files[3]);
switch (codec)
{
case VideoCodec.JpegSequence:
using (var jpeg = JpegDecoder.DecodeToLinear(bytes)) Assert.Greater(Psnr(expected, jpeg), 35);
break;
case VideoCodec.PngSequence when bitDepth == 8:
Assert.BytesEqual(PixelConvert.ToInterleaved8(expected, 3), PngDecoder.Decode(bytes).Pixels8);
break;
case VideoCodec.PngSequence:
Assert.SequenceEqual(PixelConvert.ToInterleaved16(expected, 3), PngDecoder.Decode(bytes).Pixels16!);
break;
case VideoCodec.Tiff16Sequence:
using (var tiff = TiffImageReader.Decode(bytes))
{
for (var i = 0; i < tiff.Data.Length; i += 7) Assert.Approximately(expected.Data[i], tiff.Data[i], 2e-4);
}
break;
default:
using (var dng = TiffImageReader.Decode(bytes))
{
for (var i = 0; i < dng.Data.Length; i += 7) Assert.Approximately(expected.Data[i], dng.Data[i], 1.0 / 65535);
}
break;
}
}
[Theory]
[Case(VideoCodec.Gif)]
[Case(VideoCodec.Apng)]
public void AnimationsKeepVariableDurations(VideoCodec codec)
{
var dir = _context.CreateTempDirectory();
var path = Path.Combine(dir, "out" + VideoCodecInfo.FileExtension(codec));
using (var session = new ManagedEncoderProvider().Open(Settings(path, codec))) Encode(session);
var bytes = File.ReadAllBytes(path);
var animation = codec == VideoCodec.Gif ? GifReader.Decode(bytes) : ApngReader.Decode(bytes);
Assert.Equal(3, animation.Frames.Count);
if (codec == VideoCodec.Apng)
{
Assert.SequenceEqual(new long[] { 3000, 6000, 3000 }, animation.Frames.Select(f => f.Duration90k));
using var decoded = animation.ToLinear(1);
using var expected = Frame(1);
Assert.True(Psnr(expected, decoded) > 60);
}
else
{
Assert.Approximately(12000, animation.Duration90k, 900);
using var decoded = animation.ToLinear(1);
using var expected = Frame(1);
Assert.Greater(Psnr(expected, decoded), 22);
}
}
[Theory]
[Case(VideoCodec.Mjpeg)]
[Case(VideoCodec.PngSequence)]
[Case(VideoCodec.Gif)]
[Case(VideoCodec.Apng)]
public void DisposingWithoutCompleteLeavesNothing(VideoCodec codec)
{
var dir = _context.CreateTempDirectory();
var path = Path.Combine(dir, "partial" + (VideoCodecInfo.DefaultContainer(codec) == ContainerFormat.ImageSequence ? string.Empty : VideoCodecInfo.FileExtension(codec)));
using (var session = new ManagedEncoderProvider().Open(Settings(path, codec)))
{
using var frame = Frame(0);
session.WriteFrame(frame, 3000);
session.WriteFrame(frame, 3000);
}
Assert.Empty(Directory.GetFileSystemEntries(dir));
}
[Test]
public void SequenceWriteFailuresSurfaceAndLeaveNothing()
{
var dir = _context.CreateTempDirectory();
var session = new ManagedEncoderProvider().Open(Settings(Path.Combine(dir, "seq"), VideoCodec.PngSequence));
using var frame = Frame(0);
session.WriteFrame(frame, 3000);
Directory.Delete(Directory.GetDirectories(dir, ".seq.*.tmp").Single(), recursive: true);
Exception? error = null;
try
{
for (var i = 0; i < 20; i++) session.WriteFrame(frame, 3000);
session.Complete();
}
catch (Exception ex)
{
error = ex;
}
session.Dispose();
Assert.True(error is IOException, $"unexpected {error?.GetType().Name}");
Assert.Empty(Directory.GetFileSystemEntries(dir));
}
[Test]
public void SessionsValidateTheirInput()
{
var dir = _context.CreateTempDirectory();
var provider = new ManagedEncoderProvider();
using (var session = provider.Open(Settings(Path.Combine(dir, "a.avi"), VideoCodec.Mjpeg)))
{
using var wrong = new ImageBuffer(Width + 2, Height);
Assert.Throws<ArgumentException>(() => session.WriteFrame(wrong, 3000));
Assert.Throws<InvalidOperationException>(session.Complete);
}
Assert.Empty(Directory.GetFileSystemEntries(dir));
var existing = Directory.CreateDirectory(Path.Combine(dir, "taken")).FullName;
Assert.Throws<IOException>(() => provider.Open(Settings(existing, VideoCodec.PngSequence)));
Assert.False(provider.CanEncode(Settings(Path.Combine(dir, "x.mp4"), VideoCodec.H264)));
Assert.False(provider.CanEncode(Settings(Path.Combine(dir, "x"), VideoCodec.PngSequence, bitDepth: 10)));
Assert.True(provider.CanEncode(Settings(Path.Combine(dir, "x"), VideoCodec.PngSequence, bitDepth: 16)));
Assert.Throws<NotSupportedException>(() => provider.Open(Settings(Path.Combine(dir, "x.mp4"), VideoCodec.Hevc)));
Assert.Equal(7, provider.Capabilities.Count);
Assert.True(provider.Capabilities.All(c => !c.Hardware && VideoCodecInfo.IsManaged(c.Codec)));
}
}
@@ -0,0 +1,57 @@
using Titano.Core.Imaging;
using Titano.Core.Video;
namespace Titano.Core.Tests.Render;
/// <summary>One encode recorded by <see cref="CapturingEncoderProvider"/>.</summary>
internal sealed class CapturedEncode(EncodeSettings settings)
{
public EncodeSettings Settings { get; } = settings;
public List<ImageBuffer> Frames { get; } = [];
public List<long> Durations { get; } = [];
public bool Completed { get; set; }
public bool Disposed { get; set; }
}
/// <summary>Test encoder: keeps a copy of every frame, can pretend to be hardware or to fail at a given frame.</summary>
internal sealed class CapturingEncoderProvider(string name, params EncoderCapability[] capabilities) : IVideoEncoderProvider
{
public string Name => name;
public IReadOnlyList<EncoderCapability> Capabilities => capabilities;
public List<CapturedEncode> Encodes { get; } = [];
/// <summary>When set, WriteFrame throws this for the frame with that zero-based index.</summary>
public (int Frame, Exception Error)? FailAt { get; set; }
public bool CanEncode(EncodeSettings settings) => capabilities.Any(c =>
c.Codec == settings.Codec && settings.Width <= c.MaxWidth && settings.Height <= c.MaxHeight && (settings.BitDepth == 8 || c.SupportsTenBit));
public IVideoEncoderSession Open(EncodeSettings settings)
{
var encode = new CapturedEncode(settings);
Encodes.Add(encode);
var capability = capabilities.First(c => c.Codec == settings.Codec);
return new Session(this, encode, capability);
}
private sealed class Session(CapturingEncoderProvider owner, CapturedEncode encode, EncoderCapability capability) : IVideoEncoderSession
{
public string EncoderName => capability.Name;
public bool IsHardware => capability.Hardware;
public void WriteFrame(ImageBuffer frame, long duration90k)
{
if (owner.FailAt is { } fail && fail.Frame == encode.Frames.Count) throw fail.Error;
if (frame.Width != encode.Settings.Width || frame.Height != encode.Settings.Height) throw new ArgumentException("size");
encode.Frames.Add(frame.Clone());
encode.Durations.Add(duration90k);
}
public void Complete() => encode.Completed = true;
public void Dispose() => encode.Disposed = true;
}
}
@@ -0,0 +1,20 @@
using Titano.Core.Project;
using Titano.Core.Render;
using Titano.Testing;
namespace Titano.Core.Tests.Render;
public sealed class ProjectValuesTests
{
[Test]
public void ValueTypeSettingsFallBackWithoutAdvice()
{
Assert.Equal(21, ProjectValues.Get(new Auto<int>(), 21));
Assert.Equal(180.0, ProjectValues.Get(new Auto<double>(), 180.0));
Assert.Equal(FlowQualitySetting.Balanced, ProjectValues.Get(new Auto<FlowQualitySetting>(), FlowQualitySetting.Balanced));
Assert.Equal(41, ProjectValues.Get(new Auto<int>().WithAdvice(41, null), 21));
Assert.Equal(0.5, ProjectValues.Get(new Auto<double>().WithAdvice(0.8, null).WithManual(0.5), 1.0));
Assert.Equal(FlowQualitySetting.Draft, ProjectValues.Get(new Auto<FlowQualitySetting>().WithManual(FlowQualitySetting.Draft), FlowQualitySetting.Balanced));
Assert.False(ProjectValues.Get(new Auto<bool>().WithManual(false), true));
}
}
@@ -0,0 +1,83 @@
using Titano.Core.Diagnostics.Synthetic;
using Titano.Core.Export;
using Titano.Core.Imaging;
using Titano.Core.Project;
using Titano.Core.Render;
using Titano.Core.Render.Diagnostics;
using Titano.Core.Video;
using Titano.Core.Video.Managed;
namespace Titano.Core.Tests.Render;
/// <summary>Small synthetic renders shared by the render tests.</summary>
internal static class RenderFixture
{
/// <summary>No module and no knee: the output equals the source.</summary>
public static ProjectSettings Plain { get; } = new() { Exposure = new ExposureSettings { HighlightKnee = null } };
public static SyntheticFrameSource Source(int frames = 12, double flickerEv = 0, Func<int, (double X, double Y)>? motion = null, int width = 96, int height = 64,
Func<SyntheticSequenceOptions, SyntheticSequenceOptions>? configure = null)
{
var options = new SyntheticSequenceOptions
{
Width = width,
Height = height,
FrameCount = frames,
StartEv = 0,
EndEv = 1,
FlickerEv = flickerEv,
Seed = 5,
};
return new SyntheticFrameSource(SyntheticSequence.Create(configure is null ? options : configure(options)), motion);
}
/// <summary>Renders into a capturing encoder (PNG-sequence capability) and returns the captured frames.</summary>
public static async Task<(CapturedEncode Encode, RenderResult Result)> CaptureAsync(RenderInput input, ResolvedExport? export = null, RenderOptions? options = null,
CancellationToken cancellationToken = default)
{
var capture = new CapturingEncoderProvider("capture", new EncoderCapability(VideoCodec.PngSequence, "Capture", false, 8192, 8192, true));
var target = new RenderTarget(export ?? Preset("png-sequence"), Path.Combine(Path.GetTempPath(), "titano-capture-" + Guid.NewGuid().ToString("N")));
var result = await Pipeline(capture).RenderAsync(input, target, options, cancellationToken: cancellationToken);
return (capture.Encodes.Single(), result);
}
public static RenderInput Input(SyntheticFrameSource source, ProjectSettings? project = null) =>
new() { Source = source, Frames = source.Metadata(), Project = project ?? Plain };
/// <summary>A built-in preset's values at an explicit size (0×0 = source size).</summary>
public static ResolvedExport Preset(string presetId, int width = 96, int height = 64) =>
ExportResolver.FromPreset(ExportPresets.Find(presetId)!) with { Width = width, Height = height };
public static RenderTarget Target(string folder, ResolvedExport export, string name = "out") =>
new(export, Path.Combine(folder, name + (export.Container == ContainerFormat.ImageSequence ? string.Empty : VideoCodecInfo.FileExtension(export.Codec))));
public static RenderPipeline Pipeline(params IVideoEncoderProvider[] extra) =>
new([.. extra, new ManagedEncoderProvider()]);
/// <summary>Peak signal-to-noise ratio of the 8-bit sRGB encodings.</summary>
public static double Psnr(ImageBuffer expected, ImageBuffer actual)
{
var a = PixelConvert.ToInterleaved8(expected, 3);
var b = PixelConvert.ToInterleaved8(actual, 3);
double sum = 0;
for (var i = 0; i < a.Length; i++) sum += (a[i] - b[i]) * (a[i] - b[i]);
return sum == 0 ? double.PositiveInfinity : 10 * Math.Log10(255.0 * 255 / (sum / a.Length));
}
/// <summary>Synchronous progress sink (Progress&lt;T&gt; would post to the thread pool).</summary>
public sealed class Sink<T>(Action<T> report) : IProgress<T>
{
public void Report(T value) => report(value);
}
/// <summary>Throws an <see cref="IOException"/> for one frame, as an unreadable file would.</summary>
public sealed class FailingSource(IRenderFrameSource inner, int failAt) : IRenderFrameSource
{
public int FrameCount => inner.FrameCount;
public int Width => inner.Width;
public int Height => inner.Height;
public ValueTask<ImageBuffer> GetFrameAsync(int index, int maxLongEdge, DecodePurpose purpose, CancellationToken cancellationToken) =>
index == failAt ? throw new IOException($"frame {index} is unreadable") : inner.GetFrameAsync(index, maxLongEdge, purpose, cancellationToken);
}
}
@@ -0,0 +1,69 @@
using Titano.Core.Render;
using Titano.Core.Video;
using Titano.Testing;
using static Titano.Core.Tests.Render.RenderFixture;
namespace Titano.Core.Tests.Render;
/// <summary>Process-wide observations (unobserved task exceptions, managed heap) that must not overlap other tests.</summary>
[Serial]
public sealed class RenderIsolationTests
{
private readonly TestContext _context;
public RenderIsolationTests(TestContext context) => _context = context;
[Test]
public async Task FailuresLeaveNoUnobservedTaskExceptions()
{
var unobserved = 0;
void Handler(object? sender, UnobservedTaskExceptionEventArgs e) => Interlocked.Increment(ref unobserved);
TaskScheduler.UnobservedTaskException += Handler;
try
{
var dir = _context.CreateTempDirectory();
var capture = new CapturingEncoderProvider("capture", new EncoderCapability(VideoCodec.PngSequence, "Capture", false, 4096, 4096, true))
{
FailAt = (2, new InvalidDataException("encoder broke")),
};
for (var i = 0; i < 3; i++)
{
await Assert.ThrowsAsync<InvalidDataException>(() => Pipeline(capture).RenderAsync(Input(Source()), Target(dir, Preset("png-sequence"))));
var input = Input(Source()) with { Source = new FailingSource(Source(), failAt: 3 + i) };
await Assert.ThrowsAsync<IOException>(() => Pipeline().RenderAsync(input, Target(dir, Preset("gif-preview"))));
}
GC.Collect();
GC.WaitForPendingFinalizers();
GC.Collect();
Assert.Equal(0, unobserved);
Assert.Empty(Directory.GetFileSystemEntries(dir));
}
finally
{
TaskScheduler.UnobservedTaskException -= Handler;
}
}
/// <summary>BRIEF §20.4: peak memory does not depend on the sequence length (live managed heap sampled while rendering).</summary>
[Test]
public async Task MemoryDoesNotGrowWithSequenceLength()
{
async Task<long> PeakAsync(int frames)
{
var dir = _context.CreateTempDirectory();
long peak = 0;
var progress = new Sink<RenderProgress>(p =>
{
if (p.Stage == RenderStage.Rendering && p.Done % 8 == 0) peak = Math.Max(peak, GC.GetTotalMemory(forceFullCollection: true));
});
var project = Plain with { Exposure = new Titano.Core.Project.ExposureSettings { Deflicker = new Titano.Core.Project.Auto<bool>().WithManual(true) } };
await Pipeline().RenderAsync(Input(Source(frames), project), Target(dir, Preset("mjpeg-avi")), progress: progress, cancellationToken: _context.Cancellation);
return peak;
}
await PeakAsync(16);
var shortPeak = await PeakAsync(48);
var longPeak = await PeakAsync(192);
_context.Log($"peak live heap: 48 frames {shortPeak / 1024} KiB, 192 frames {longPeak / 1024} KiB");
Assert.Less(longPeak - shortPeak, 2 << 20);
}
}
@@ -0,0 +1,208 @@
using Titano.Core.Codecs.Jpeg;
using Titano.Core.Codecs.Png;
using Titano.Core.Codecs.Tiff;
using Titano.Core.Export;
using Titano.Core.Imaging;
using Titano.Core.Project;
using Titano.Core.Render;
using Titano.Core.Render.Diagnostics;
using Titano.Core.Video;
using Titano.Core.Video.Managed;
using Titano.Testing;
using static Titano.Core.Tests.Render.RenderFixture;
namespace Titano.Core.Tests.Render;
public sealed class RenderPipelineTests
{
private readonly TestContext _context;
public RenderPipelineTests(TestContext context) => _context = context;
[Theory]
[Case("mjpeg-avi", 8)]
[Case("jpeg-sequence", 8)]
[Case("png-sequence", 8)]
[Case("png-sequence", 16)]
[Case("tiff16-sequence", 16)]
[Case("dng-sequence", 16)]
[Case("gif-preview", 8)]
[Case("apng", 8)]
public async Task RendersEveryManagedFormat(string presetId, int bitDepth)
{
var dir = _context.CreateTempDirectory();
var source = Source();
var export = Preset(presetId) with { BitDepth = bitDepth };
var target = Target(dir, export);
var result = await Pipeline().RenderAsync(Input(source), target, cancellationToken: _context.Cancellation);
Assert.Equal(target.OutputPath, result.OutputPath);
Assert.SequenceEqual(new[] { Path.GetFileName(target.OutputPath) }, Directory.GetFileSystemEntries(dir).Select(Path.GetFileName));
Assert.Equal((96, 64), (result.Width, result.Height));
Assert.Equal(12, result.FrameCount);
Assert.Equal(RenderResultBytes(target.OutputPath), result.Bytes);
Assert.False(result.Hardware);
Assert.Approximately(12 / export.FrameRate.Value, result.DurationSeconds, 1e-4);
using var expected = source.Sequence.Render(5);
using var decoded = DecodeFrame(export.Codec, target.OutputPath, 5, out var count);
Assert.Equal(12, count);
var psnr = Psnr(expected, decoded);
_context.Log($"{presetId} {bitDepth}-bit: {result.Bytes} bytes, PSNR {psnr:F1} dB");
Assert.Greater(psnr, export.Codec switch { VideoCodec.Gif => 25, VideoCodec.Mjpeg or VideoCodec.JpegSequence => 35, _ => 60 });
}
[Test]
public async Task LosslessOutputsAreByteIdenticalAcrossRuns()
{
var dir = _context.CreateTempDirectory();
var project = Plain with
{
Exposure = new ExposureSettings { Deflicker = new Auto<bool>().WithManual(true), HighlightKnee = 0.9 },
Timing = new TimingSettings { Mode = new Auto<TimingMode>().WithManual(TimingMode.Interpolated), FrameRate = new Auto<string>().WithManual("15") },
};
var first = await Pipeline().RenderAsync(Input(Source(flickerEv: 0.2), project), Target(dir, Preset("png-sequence"), "a"), cancellationToken: _context.Cancellation);
var second = await Pipeline().RenderAsync(Input(Source(flickerEv: 0.2), project), Target(dir, Preset("png-sequence"), "b"), cancellationToken: _context.Cancellation);
var a = Directory.GetFiles(first.OutputPath).Order(StringComparer.Ordinal).ToArray();
var b = Directory.GetFiles(second.OutputPath).Order(StringComparer.Ordinal).ToArray();
Assert.Equal(a.Length, b.Length);
Assert.Greater(first.FrameCount, 12);
for (var i = 0; i < a.Length; i++) Assert.BytesEqual(File.ReadAllBytes(a[i]), File.ReadAllBytes(b[i]));
var apngA = await Pipeline().RenderAsync(Input(Source(), project), Target(dir, Preset("apng"), "c"), cancellationToken: _context.Cancellation);
var apngB = await Pipeline().RenderAsync(Input(Source(), project), Target(dir, Preset("apng"), "d"), cancellationToken: _context.Cancellation);
Assert.BytesEqual(File.ReadAllBytes(apngA.OutputPath), File.ReadAllBytes(apngB.OutputPath));
}
[Theory]
[Case("mjpeg-avi")]
[Case("png-sequence")]
[Case("gif-preview")]
public async Task CancellationLeavesNoOutput(string presetId)
{
var dir = _context.CreateTempDirectory();
using var cts = CancellationTokenSource.CreateLinkedTokenSource(_context.Cancellation);
var progress = new Sink<RenderProgress>(p =>
{
if (p.Stage == RenderStage.Rendering && p.Done == 5) cts.Cancel();
});
await Assert.ThrowsAsync<OperationCanceledException>(() => Pipeline().RenderAsync(Input(Source(24)), Target(dir, Preset(presetId)), progress: progress, cancellationToken: cts.Token));
Assert.Empty(Directory.GetFileSystemEntries(dir));
}
[Test]
public async Task SourceFailurePropagatesOnceAndLeavesNoOutput()
{
var dir = _context.CreateTempDirectory();
var input = Input(Source()) with { Source = new FailingSource(Source(), failAt: 7) };
var error = await Assert.ThrowsAsync<IOException>(() => Pipeline().RenderAsync(input, Target(dir, Preset("mjpeg-avi"))));
Assert.Equal("frame 7 is unreadable", error.Message);
Assert.Empty(Directory.GetFileSystemEntries(dir));
}
[Test]
public async Task EncoderFailurePropagatesAndDisposesTheSession()
{
var capture = new CapturingEncoderProvider("capture", new EncoderCapability(VideoCodec.PngSequence, "Capture", false, 4096, 4096, true))
{
FailAt = (4, new InvalidDataException("encoder broke")),
};
var error = await Assert.ThrowsAsync<InvalidDataException>(() => Pipeline(capture).RenderAsync(Input(Source()), Target(_context.CreateTempDirectory(), Preset("png-sequence"))));
Assert.Equal("encoder broke", error.Message);
var encode = capture.Encodes.Single();
Assert.True(encode.Disposed);
Assert.False(encode.Completed);
Assert.Equal(4, encode.Frames.Count);
}
[Test]
public async Task ProgressReportsEveryFrameAndPreviews()
{
var reports = new List<RenderProgress>();
var options = new RenderOptions { PreviewInterval = 5, PreviewLongEdge = 32 };
var project = Plain with { Exposure = new ExposureSettings { Deflicker = new Auto<bool>().WithManual(true), HighlightKnee = null } };
await Pipeline().RenderAsync(Input(Source(), project), Target(_context.CreateTempDirectory(), Preset("jpeg-sequence")), options,
new Sink<RenderProgress>(reports.Add), _context.Cancellation);
var preparing = reports.Where(r => r.Stage == RenderStage.Preparing).ToList();
var rendering = reports.Where(r => r.Stage == RenderStage.Rendering).ToList();
Assert.Equal(12, preparing.Count);
Assert.SequenceEqual(Enumerable.Range(1, 12), rendering.Select(r => r.Done));
Assert.True(rendering.All(r => r.Total == 12 && r.FramesPerSecond > 0 && r.Remaining >= TimeSpan.Zero));
Assert.SequenceEqual(new[] { 1, 6, 11 }, rendering.Where(r => r.Preview is not null).Select(r => r.Done));
Assert.Equal(32, rendering[0].Preview!.Width);
Assert.Equal(RenderStage.Finishing, reports[^1].Stage);
foreach (var r in rendering) r.Preview?.Dispose();
}
[Test]
public async Task BatchRendersEachTargetAndReportsFailures()
{
var dir = _context.CreateTempDirectory();
var server = new RenderPipeline([new ManagedEncoderProvider()], EncoderHost.Server);
var targets = new[]
{
Target(dir, Preset("png-sequence"), "png"),
Target(dir, Preset("1080p-h264"), "h264"),
Target(dir, Preset("gif-preview"), "gif"),
};
var results = await server.RenderBatchAsync(Input(Source()), targets, cancellationToken: _context.Cancellation);
Assert.Equal(3, results.Count);
Assert.True(results[0].Succeeded && results[2].Succeeded);
var error = Assert.NotNull(results[1].Error as RenderException);
Assert.Equal(EncoderNotices.NeedsRenderNode, error.ReasonKey);
Assert.SequenceEqual(new[] { "gif.gif", "png" }, Directory.GetFileSystemEntries(dir).Select(Path.GetFileName).Order(StringComparer.Ordinal));
}
[Test]
public async Task EverythingExcludedIsARenderError()
{
var project = Plain with { ExcludedFrames = [.. Enumerable.Range(0, 12)] };
var error = await Assert.ThrowsAsync<RenderException>(() => Pipeline().RenderAsync(Input(Source(), project), Target(_context.CreateTempDirectory(), Preset("png-sequence"))));
Assert.Equal("Export.Render.NoFrames", error.ReasonKey);
}
[Test]
public async Task ResultBecomesARenderHistoryEntity()
{
var result = await Pipeline().RenderAsync(Input(Source()), Target(_context.CreateTempDirectory(), Preset("apng")), cancellationToken: _context.Cancellation);
var sequence = Guid.CreateVersion7();
var entity = result.ToEntity(sequence, "APNG", "{}", "test");
Assert.Equal(sequence, entity.SequenceId);
Assert.Equal(result.OutputPath, entity.OutputPath);
Assert.Equal("Apng", entity.Codec);
Assert.Equal(result.Bytes, entity.Bytes);
Assert.Approximately(15, entity.Fps, 1e-12);
Assert.Equal("Managed APNG", result.EncoderName);
}
private static long RenderResultBytes(string path) => File.Exists(path)
? new FileInfo(path).Length
: new DirectoryInfo(path).EnumerateFiles().Sum(f => f.Length);
/// <summary>Decodes output picture <paramref name="index"/> and counts the pictures of the output.</summary>
private static ImageBuffer DecodeFrame(VideoCodec codec, string path, int index, out int count)
{
switch (codec)
{
case VideoCodec.Mjpeg:
var avi = AviReader.Read(File.ReadAllBytes(path));
count = avi.Frames.Count;
return JpegDecoder.DecodeToLinear(avi.Frames[index]);
case VideoCodec.Gif or VideoCodec.Apng:
var bytes = File.ReadAllBytes(path);
var animation = codec == VideoCodec.Gif ? GifReader.Decode(bytes) : ApngReader.Decode(bytes);
count = animation.Frames.Count;
return animation.ToLinear(index);
default:
var files = Directory.GetFiles(path).Order(StringComparer.Ordinal).ToArray();
count = files.Length;
var data = File.ReadAllBytes(files[index]);
return codec switch
{
VideoCodec.JpegSequence => JpegDecoder.DecodeToLinear(data),
VideoCodec.PngSequence => PngDecoder.DecodeToLinear(data),
_ => TiffImageReader.Decode(data),
};
}
}
}
@@ -0,0 +1,202 @@
using Titano.Core.Project;
using Titano.Core.Render;
using Titano.Core.Video;
using Titano.Testing;
namespace Titano.Core.Tests.Render;
public sealed class RenderPlanTests
{
private static readonly DateTime Start = new(2024, 6, 21, 19, 0, 0);
private static DateTime?[] Regular(int count, double interval = 10) =>
Enumerable.Range(0, count).Select(i => (DateTime?)Start.AddSeconds(i * interval)).ToArray();
private static ProjectSettings Timing(TimingMode mode, string? playback = null, double? fit = null, IReadOnlyList<CurvePoint>? curve = null, int[]? excluded = null) => new()
{
Timing = new TimingSettings
{
Mode = new Auto<TimingMode>().WithManual(mode),
FrameRate = playback is null ? new Auto<string>() : new Auto<string>().WithManual(playback),
FitToSeconds = fit,
RemapCurve = curve ?? [new(0, 0), new(1, 1)],
},
ExcludedFrames = excluded ?? [],
};
private static void AssertExactDurations(RenderPlan plan)
{
Assert.Equal(plan.Duration90k, plan.Frames.Sum(f => f.Duration90k));
Assert.Equal(RenderPlan.TicksAt(plan.FrameRate, plan.SlotCount), plan.Duration90k);
long t = 0;
var slot = 0;
foreach (var f in plan.Frames)
{
Assert.Equal(t, f.Start90k);
Assert.Equal(slot, f.StartSlot);
Assert.Greater(f.Duration90k, 0);
t += f.Duration90k;
slot += f.Slots;
}
Assert.Equal(plan.SlotCount, slot);
Assert.Monotonic(plan.Frames.Select(f => f.SourcePosition));
}
[Test]
public void ConstantShowsEveryFrameOnceAtTheOutputRate()
{
var plan = RenderPlan.Build(Regular(100), Timing(TimingMode.Constant), new Rational(24, 1));
Assert.Equal(100, plan.Frames.Count);
Assert.SequenceEqual(Enumerable.Range(0, 100).Select(i => (double)i), plan.Frames.Select(f => f.SourcePosition));
Assert.True(plan.Frames.All(f => f.Duration90k == 3750 && f.Flags == PlannedFrameFlags.None && f.Speed == 1));
Assert.Equal(375_000L, plan.Duration90k);
AssertExactDurations(plan);
}
[Test]
public void ExcludedFramesAreSkipped()
{
var plan = RenderPlan.Build(Regular(20), Timing(TimingMode.Constant, excluded: [3, 7, 99]), new Rational(25, 1));
Assert.Equal(18, plan.Frames.Count);
Assert.DoesNotContain(3, plan.Frames.Select(f => f.From));
Assert.DoesNotContain(7, plan.Frames.Select(f => f.To));
Assert.Equal(2, plan.Statistics.ExcludedFrames);
Assert.Equal(2.0, plan.Frames.Single(f => f.From == 2).Speed);
AssertExactDurations(plan);
}
[Test]
public void NtscDurationsAccumulateWithoutDrift()
{
var plan = RenderPlan.Build(Regular(1001), Timing(TimingMode.Constant), Rational.Fps2997);
Assert.Equal(1001 * 3003L, plan.Duration90k);
Assert.True(plan.Frames.All(f => f.Duration90k == 3003));
var fps23 = RenderPlan.Build(Regular(7), Timing(TimingMode.Constant), Rational.Fps23976);
Assert.SequenceEqual(new long[] { 3754, 3754, 3753, 3754, 3754, 3754, 3753 }, fps23.Frames.Select(f => f.Duration90k));
Assert.Equal(26_276L, fps23.Duration90k);
AssertExactDurations(fps23);
}
[Test]
public void SlowerPlaybackHoldsFramesInConstantAndSynthesisesInInterpolated()
{
var held = RenderPlan.Build(Regular(10), Timing(TimingMode.Constant, playback: "12"), new Rational(24, 1));
Assert.Equal(10, held.Frames.Count);
Assert.True(held.Frames.All(f => f.Slots == 2 && f.IsHeld && f.Duration90k == 7500));
AssertExactDurations(held);
var smooth = RenderPlan.Build(Regular(10), Timing(TimingMode.Interpolated, playback: "12"), new Rational(24, 1));
Assert.Equal(19, smooth.Frames.Count);
Assert.Equal(9, smooth.Statistics.InterpolatedFrames);
Assert.Equal(0.5, smooth.Frames[1].SourcePosition);
Assert.Equal(0.5, smooth.Frames[1].Fraction);
Assert.Equal(9.0, smooth.Frames[^1].SourcePosition);
Assert.True(smooth.Frames[^1].IsHeld, "the last frame has no successor to blend towards");
AssertExactDurations(smooth);
}
[Test]
public void FitToSecondsScalesThePlan()
{
var shorter = RenderPlan.Build(Regular(100), Timing(TimingMode.Constant, fit: 2), new Rational(25, 1));
Assert.Equal(50, shorter.SlotCount);
Assert.Equal(180_000L, shorter.Duration90k);
Assert.True(shorter.Frames.All(f => f.Fraction == 0 && f.SourcePosition % 2 == 0));
Assert.Equal(50, shorter.Statistics.SkippedFrames);
Assert.Approximately(2.0, shorter.Statistics.MaximumSpeed, 1e-9);
var longer = RenderPlan.Build(Regular(100), Timing(TimingMode.Interpolated, fit: 7.96), new Rational(25, 1));
Assert.Equal(199, longer.SlotCount);
Assert.Equal(716_400L, longer.Duration90k);
Assert.Greater(longer.Statistics.InterpolatedFrames, 90);
AssertExactDurations(longer);
}
[Test]
public void AdaptiveFollowsCaptureTimeAndShortensPauses()
{
var times = Regular(40);
for (var i = 11; i < 40; i++) times[i] = times[i]!.Value.AddSeconds(10); // 2× interval into frame 11
for (var i = 21; i < 40; i++) times[i] = times[i]!.Value.AddSeconds(60); // 7× gap into frame 21
for (var i = 31; i < 40; i++) times[i] = times[i]!.Value.AddHours(1); // deliberate pause into frame 31
var plan = RenderPlan.Build(times, Timing(TimingMode.Adaptive), new Rational(24, 1));
Assert.Equal(40, plan.Frames.Count);
Assert.Equal(2, plan.Frames[10].Slots);
Assert.Equal(4, plan.Frames[20].Slots); // 3 + log2(7/3) = 4.22 periods, rounded on the grid
Assert.Equal(5, plan.Frames[30].Slots); // 0.2 s × 24 fps = 4.8 periods
Assert.True(plan.Frames.Where((_, i) => i is not (10 or 20 or 30)).All(f => f.Slots == 1));
Assert.False(plan.IsCutBefore(11));
Assert.True(plan.IsCutBefore(21));
Assert.True(plan.IsCutBefore(31));
Assert.Equal(-1, plan.NextContinuous(30));
Assert.Equal(29, plan.PreviousContinuous(30));
Assert.Equal(2, plan.Statistics.Cuts);
Assert.Approximately(10.0, plan.Statistics.MedianIntervalSeconds!.Value, 1e-9);
AssertExactDurations(plan);
}
[Test]
public void InterpolatedFillsMissingAndExcludedFrames()
{
var times = Regular(40);
for (var i = 20; i < 40; i++) times[i] = times[i]!.Value.AddSeconds(10); // one capture missing before frame 20
for (var i = 35; i < 40; i++) times[i] = times[i]!.Value.AddSeconds(600); // too long to synthesise
var plan = RenderPlan.Build(times, Timing(TimingMode.Interpolated, excluded: [30]), new Rational(30, 1));
var gap = plan.Frames.Single(f => f.From == 19 && f.IsInterpolated);
Assert.Equal(19.5, gap.SourcePosition);
Assert.Equal(20, gap.To);
var excluded = plan.Frames.Single(f => f.From == 29 && f.IsInterpolated);
Assert.Equal(30.0, excluded.SourcePosition);
Assert.Equal(31, excluded.To);
Assert.Equal(0.5, excluded.Fraction);
Assert.True(plan.IsCutBefore(35));
Assert.False(plan.Frames.Any(f => f.From == 34 && f.IsInterpolated));
Assert.Equal(41, plan.Frames.Count);
AssertExactDurations(plan);
}
[Test]
public void RemapIsMonotoneEvenForBadCurves()
{
var ease = RenderPlan.Build(Regular(120), Timing(TimingMode.Remapped, curve: [new(0, 0), new(0.5, 0.2), new(1, 1)]), new Rational(24, 1));
AssertExactDurations(ease);
Assert.Equal(120, ease.SlotCount);
Assert.Equal(0.0, ease.Frames[0].SourcePosition);
Assert.Greater(ease.Frames[^1].SourcePosition, 115);
Assert.Less(ease.Frames[^1].Speed * ease.Frames[^1].Slots, 3.5);
Assert.Less(ease.Frames[10].Speed, 0.5);
Assert.Empty(ease.Warnings);
var bad = RenderPlan.Build(Regular(60), Timing(TimingMode.Remapped, curve: [new(1, 1), new(0, 0.1), new(0.4, 0.8), new(0.6, 0.3)]), new Rational(24, 1));
Assert.Contains("Export.Plan.RemapNotMonotonic", bad.Warnings);
AssertExactDurations(bad);
Assert.Approximately(0.1 * 60, bad.Frames[0].SourcePosition, 1e-9);
}
[Test]
public void AnUnreadablePlaybackRateFallsBackToTheOutputRate()
{
var plan = RenderPlan.Build(Regular(10), Timing(TimingMode.Constant, playback: "fast"), new Rational(25, 1));
Assert.Contains("Export.Plan.FrameRateIgnored", plan.Warnings);
Assert.Equal(10, plan.SlotCount);
Assert.Equal(25.0, plan.PlaybackRate);
}
[Test]
public void EverythingExcludedGivesAnEmptyPlan()
{
var plan = RenderPlan.Build(Regular(3), Timing(TimingMode.Constant, excluded: [0, 1, 2]), new Rational(30, 1));
Assert.Empty(plan.Frames);
Assert.Equal(0L, plan.Duration90k);
Assert.Contains("Export.Plan.NoFrames", plan.Warnings);
}
[Test]
public void AdaptiveWithoutCaptureTimesFallsBackToConstantPacing()
{
var plan = RenderPlan.Build(new DateTime?[12], Timing(TimingMode.Adaptive), new Rational(30, 1));
Assert.Equal(12, plan.Frames.Count);
Assert.Contains("Export.Plan.NoCaptureTimes", plan.Warnings);
AssertExactDurations(plan);
}
}
@@ -0,0 +1,371 @@
using Titano.Core.Analysis;
using Titano.Core.Diagnostics.Synthetic;
using Titano.Core.Imaging;
using Titano.Core.Imaging.Geometry;
using Titano.Core.Motion;
using Titano.Core.Project;
using Titano.Core.Render;
using Titano.Core.Render.Diagnostics;
using Titano.Testing;
using static Titano.Core.Tests.Render.RenderFixture;
namespace Titano.Core.Tests.Render;
public sealed class RenderProcessingTests
{
private readonly TestContext _context;
public RenderProcessingTests(TestContext context) => _context = context;
private static ProjectSettings With(ExposureSettings? exposure = null, MotionSettings? motion = null, CameraSettings? camera = null, StackSettings? stack = null,
TimingSettings? timing = null) => Plain with
{
Exposure = exposure ?? Plain.Exposure,
Motion = motion ?? new MotionSettings(),
Camera = camera ?? new CameraSettings(),
Stack = stack ?? new StackSettings(),
Timing = timing ?? new TimingSettings(),
};
private static Auto<T> On<T>(T value) => new Auto<T>().WithManual(value);
private static double[] LogLuminance(IEnumerable<ImageBuffer> frames) => [.. frames.Select(f => FrameStatistics.MeasureLogLuminance(f))];
private static double Rms(IEnumerable<double> values)
{
var v = values.ToArray();
var mean = v.Average();
return Math.Sqrt(v.Sum(x => (x - mean) * (x - mean)) / v.Length);
}
/// <summary>The §20.4 deflicker gate measured on rendered frames (same recipe as the analysis gate).</summary>
[Test]
public async Task DeflickerRemovesFlickerAndKeepsTheRamp()
{
var source = Source(200, configure: o => o with { Seed = 3, StartEv = -2, EndEv = 1, FlickerEv = 0.1 });
var project = With(new ExposureSettings { Deflicker = On(true), DeflickerWindow = On(21), HighlightKnee = null });
var (encode, _) = await CaptureAsync(Input(source, project), cancellationToken: _context.Cancellation);
var truth = source.Sequence.SceneEv;
var measured = Analysis.AnalysisFixtures.MeasureSeries(source.Sequence);
var output = LogLuminance(encode.Frames);
var before = Analysis.AnalysisFixtures.FrameToFrameResidualRms(measured, truth);
var after = Analysis.AnalysisFixtures.FrameToFrameResidualRms(output, truth);
var rampError = Analysis.AnalysisFixtures.MaxDeviation(output, truth);
_context.Log($"flicker {before:F4} → {after:F4} EV ({1 - after / before:P0}); max ramp deviation {rampError:F4} EV");
Assert.GreaterOrEqual(1 - after / before, 0.6);
Assert.LessOrEqual(rampError, 0.05);
}
[Test]
public async Task HolyGrailTurnsExposureStepsIntoRamps()
{
var source = Source(80, configure: o => o with { ExposureSteps = [new SyntheticExposureStep(40, 1.0)], StartEv = 0, EndEv = 0 });
var project = With(new ExposureSettings { HolyGrail = On(true), Deflicker = On(true), HighlightKnee = null });
var (encode, _) = await CaptureAsync(Input(source, project), cancellationToken: _context.Cancellation);
var output = LogLuminance(encode.Frames);
var steps = output.Zip(output.Skip(1), (a, b) => Math.Abs(b - a)).ToArray();
_context.Log($"largest output step {steps.Max():F3} EV");
Assert.LessOrEqual(steps.Max(), 0.3 + 0.02);
Assert.Approximately(-1.0, output[^1] - output[0], 0.1, "the step is kept, only spread out");
}
[Test]
public async Task ExcludedFramesDoNotCreateExposureSteps()
{
// Frame 10 is a test shot one stop darker; excluding it must leave no holy-grail step behind.
var source = Source(30, configure: o => o with { ExposureSteps = [new SyntheticExposureStep(10, 1.0), new SyntheticExposureStep(11, -1.0)], StartEv = 0, EndEv = 0 });
var project = With(new ExposureSettings { HolyGrail = On(true), HighlightKnee = null });
var all = await RenderPreparation.PrepareAsync(Input(source, project), cancellationToken: _context.Cancellation);
var excluded = await RenderPreparation.PrepareAsync(Input(source, project with { ExcludedFrames = [10] }), cancellationToken: _context.Cancellation);
Assert.Count(2, all.Report.Transitions);
Assert.Empty(excluded.Report.Transitions);
Assert.True(double.IsNaN(excluded.MeasuredLogLuminance[10]));
}
[Test]
public async Task WhiteBalanceSmoothingRemovesColourJitter()
{
var source = Source(48, configure: o => o with { WhiteBalanceJitter = 0.1 });
var (encode, _) = await CaptureAsync(Input(source, With(new ExposureSettings { WhiteBalanceSmoothing = On(true), HighlightKnee = null })), cancellationToken: _context.Cancellation);
double Ratio(ImageBuffer f)
{
var stats = FrameStatistics.Measure(f);
return Math.Log2(stats.MeanRed / stats.MeanGreen);
}
var before = Enumerable.Range(0, 48).Select(i =>
{
using var f = source.Sequence.Render(i);
return Ratio(f);
}).ToArray();
var after = encode.Frames.Select(Ratio).ToArray();
double Jitter(double[] r) => Rms(r.Zip(r.Skip(1), (a, b) => b - a));
_context.Log($"R/G jitter {Jitter(before):F4} → {Jitter(after):F4}");
Assert.Less(Jitter(after), 0.3 * Jitter(before));
}
[Test]
public async Task RegionDeflickerCorrectsSkyAndLandSeparately()
{
var source = Source(48, configure: o => o with { SkyFlickerEv = 0.3, LandFlickerEv = 0.3, StartEv = 0, EndEv = 0 });
var landMask = new float[96 * 64];
for (var y = 0; y < 64; y++)
{
for (var x = 0; x < 96; x++) landMask[y * 96 + x] = source.Sequence.IsSky(x, y) ? 0 : 1;
}
double LandResidual(List<ImageBuffer> frames) => Rms(frames.Select(f => FrameStatistics.MeasureLogLuminance(f, landMask)));
var global = await CaptureAsync(Input(source, With(new ExposureSettings { Deflicker = On(true), HighlightKnee = null })), cancellationToken: _context.Cancellation);
var regions = await CaptureAsync(Input(source, With(new ExposureSettings { Deflicker = On(true), Regions = On(RegionMode.Horizon), HighlightKnee = null })),
cancellationToken: _context.Cancellation);
var g = LandResidual(global.Encode.Frames);
var r = LandResidual(regions.Encode.Frames);
_context.Log($"land residual global {g:F3} EV, regions {r:F3} EV");
Assert.Less(r, 0.5 * g);
var prepared = await RenderPreparation.PrepareAsync(Input(source, With(new ExposureSettings { Deflicker = On(true), Regions = On(RegionMode.Horizon) })),
cancellationToken: _context.Cancellation);
Assert.Equal(RegionMethod.Horizon, prepared.Report.RegionMethod);
Assert.NotNull(prepared.SkyEv);
}
[Test]
public async Task ExportAspectCropsTheCentreAndCameraCropMovesIt()
{
var source = Source(4);
using var reference = source.Sequence.Render(2);
var (square, _) = await CaptureAsync(Input(source), Preset("png-sequence", 64, 64), cancellationToken: _context.Cancellation);
using (var expected = GeometryStage.Apply(reference, new GeometrySettings { Crop = new RectD(16, 0, 64, 64), OutputWidth = 64, OutputHeight = 64 }))
Assert.Greater(Psnr(expected, square.Frames[2]), 60);
var quarter = With(camera: new CameraSettings { Crop = [0.5, 0.5, 0.5, 0.5] });
var (corner, result) = await CaptureAsync(Input(source, quarter), Preset("png-sequence", 0, 0), cancellationToken: _context.Cancellation);
Assert.Equal((48, 32), (result.Width, result.Height));
using (var expected = GeometryStage.Apply(reference, new GeometrySettings { Crop = new RectD(48, 32, 48, 32) }))
Assert.Greater(Psnr(expected, corner.Frames[2]), 60);
}
[Test]
public async Task VirtualCameraZoomsAndTheDecodeSizeFollowsTheNeed()
{
var plain = Source(4, width: 480, height: 320);
await CaptureAsync(Input(plain), Preset("png-sequence", 96, 64), cancellationToken: _context.Cancellation);
Assert.Equal(96, plain.LargestRenderRequest);
var zoomed = Source(4, width: 480, height: 320);
var camera = With(camera: new CameraSettings { Keyframes = [new CameraKey(0, 0.5, 0.5, 2, 0), new CameraKey(3, 0.5, 0.5, 2, 0)] });
var (encode, _) = await CaptureAsync(Input(zoomed, camera), Preset("png-sequence", 96, 64), cancellationToken: _context.Cancellation);
Assert.Equal(192, zoomed.LargestRenderRequest);
var capped = Source(4, width: 480, height: 320);
await CaptureAsync(Input(capped, camera), Preset("png-sequence", 96, 64), new RenderOptions { MaxWorkingLongEdge = 120 }, _context.Cancellation);
Assert.Equal(120, capped.LargestRenderRequest);
using var full = zoomed.Sequence.Render(1);
using var expected = GeometryStage.Apply(full, new GeometrySettings { Crop = new RectD(120, 80, 240, 160), OutputWidth = 96, OutputHeight = 64 });
var psnr = Psnr(expected, encode.Frames[1]);
_context.Log($"zoom ×2 vs direct crop: {psnr:F1} dB");
Assert.Greater(psnr, 28);
}
[Test]
public async Task ExposureOffsetAndKneeAreApplied()
{
var source = Source(3, configure: o => o with { StartEv = 2, EndEv = 2 });
var (raw, _) = await CaptureAsync(Input(source), cancellationToken: _context.Cancellation);
var (brighter, _) = await CaptureAsync(Input(source, With(new ExposureSettings { ExposureOffsetEv = 1, HighlightKnee = null })), cancellationToken: _context.Cancellation);
for (var i = 0; i < raw.Frames[0].Data.Length; i += 13) Assert.Approximately(2 * raw.Frames[0].Data[i], brighter.Frames[0].Data[i], 1e-5);
Assert.Greater(raw.Frames[0].Data.ToArray().Max(), 1f);
var (kneed, _) = await CaptureAsync(Input(source, With(new ExposureSettings { HighlightKnee = 0.8 })), cancellationToken: _context.Cancellation);
Assert.Less(kneed.Frames[0].Data.ToArray().Max(), 1f);
for (var i = 0; i < raw.Frames[0].Data.Length; i += 13)
{
if (raw.Frames[0].Data[i] < 0.5f) Assert.Approximately(raw.Frames[0].Data[i], kneed.Frames[0].Data[i], 1e-6);
}
}
[Test]
public async Task InterpolatedFramesFollowTheMotion()
{
Func<int, (double, double)> pan = i => (2.0 * i, 0);
var source = Source(6, motion: pan, configure: o => o with { StartEv = 0, EndEv = 0 });
var timing = new TimingSettings { Mode = On(TimingMode.Interpolated), FrameRate = new Auto<string>().WithManual("15") };
var export = Preset("png-sequence") with { FrameRate = new Titano.Core.Video.Rational(30, 1) };
var (encode, result) = await CaptureAsync(Input(source, With(timing: timing)), export, cancellationToken: _context.Cancellation);
Assert.Equal(11, result.FrameCount);
Assert.Equal(12, encode.Durations.Sum() / 3000);
var truth = Source(6, motion: i => (2.0 * i + 1, 0), configure: o => o with { StartEv = 0, EndEv = 0 });
using var shifted = await truth.GetFrameAsync(2, 0, DecodePurpose.Render, _context.Cancellation);
double Interior(ImageBuffer a, ImageBuffer b)
{
using var ca = GeometryStage.Apply(a, new GeometrySettings { Crop = new RectD(12, 4, 72, 56) });
using var cb = GeometryStage.Apply(b, new GeometrySettings { Crop = new RectD(12, 4, 72, 56) });
return Psnr(ca, cb);
}
var synthesised = Interior(shifted, encode.Frames[5]);
var nearest = Interior(shifted, encode.Frames[4]);
_context.Log($"synthesised frame {synthesised:F1} dB vs nearest whole frame {nearest:F1} dB");
Assert.Greater(synthesised, 30);
Assert.Greater(synthesised, nearest + 5);
}
[Test]
public async Task MotionBlurSmearsAlongTheMotionOnly()
{
var blur = new MotionSettings { MotionBlur = On(true), TargetShutterAngle = On(360.0) };
var moving = Source(6, motion: i => (3.0 * i, 0), configure: o => o with { StartEv = 0, EndEv = 0 });
var sharp = await CaptureAsync(Input(moving), cancellationToken: _context.Cancellation);
var blurred = await CaptureAsync(Input(moving, With(motion: blur)), cancellationToken: _context.Cancellation);
double Gradient(ImageBuffer f, int dx, int dy)
{
double sum = 0;
var g = f.Plane(1);
for (var y = 8; y < f.Height - 8; y++)
{
for (var x = 8; x < f.Width - 8; x++) sum += Math.Abs(g[y * f.Width + x] - g[(y + dy) * f.Width + x + dx]);
}
return sum;
}
var horizontal = Gradient(blurred.Encode.Frames[3], 1, 0) / Gradient(sharp.Encode.Frames[3], 1, 0);
var vertical = Gradient(blurred.Encode.Frames[3], 0, 1) / Gradient(sharp.Encode.Frames[3], 0, 1);
_context.Log($"gradient ratios: horizontal {horizontal:F3}, vertical {vertical:F3}");
Assert.Less(horizontal, 0.75);
Assert.Greater(vertical, horizontal + 0.1);
var still = Source(6, configure: o => o with { StartEv = 0, EndEv = 0 });
var a = await CaptureAsync(Input(still), cancellationToken: _context.Cancellation);
var b = await CaptureAsync(Input(still, With(motion: blur)), cancellationToken: _context.Cancellation);
Assert.Greater(Psnr(a.Encode.Frames[3], b.Encode.Frames[3]), 40);
}
[Test]
public async Task StabilisationRemovesShake()
{
var random = new Random(11);
var shake = Enumerable.Range(0, 24).Select(_ => (X: random.NextDouble() * 6 - 3, Y: random.NextDouble() * 6 - 3)).ToArray();
var source = new PatternFrameSource(320, 192, 24, i => shake[i]);
var project = With(motion: new MotionSettings { Stabilize = On(true), StabilizeSmoothing = On(12.0) });
var input = new RenderInput { Source = source, Frames = source.Metadata(), Project = project };
static double Steps(IReadOnlyList<(double X, double Y)> p) =>
Math.Sqrt(Enumerable.Range(1, p.Count - 1).Average(k => Math.Pow(p[k].X - p[k - 1].X, 2) + Math.Pow(p[k].Y - p[k - 1].Y, 2)));
var prepared = await RenderPreparation.PrepareAsync(input, cancellationToken: _context.Cancellation);
var residual = Enumerable.Range(0, 24).Select(k =>
{
var (x, y) = prepared.Stabilization![k].Apply(159.5, 95.5);
return (shake[k].X + x - 159.5, shake[k].Y + y - 95.5);
}).ToArray();
_context.Log($"camera path steps {Steps(shake):F2} px → {Steps(residual):F3} px after correction; zoom {prepared.StabilizationZoom:F3}");
Assert.Less(Steps(residual), 0.1 * Steps(shake));
Assert.InRange(prepared.StabilizationZoom, 1.01, 1.2);
var (encode, result) = await CaptureAsync(input, Preset("png-sequence", 0, 0), cancellationToken: _context.Cancellation);
Assert.Equal((320, 192), (result.Width, result.Height));
using var stabilizer = new Stabilizer(320, 192);
var output = encode.Frames.Select(f => stabilizer.AddFrame(f).Transform).Skip(1).ToArray();
var after = Math.Sqrt(output.Average(m => m.Tx * m.Tx + m.Ty * m.Ty));
_context.Log($"rendered frame-to-frame shift {after:F3} px");
Assert.Less(after, 0.1 * Steps(shake) * prepared.StabilizationZoom);
}
[Test]
public async Task MedianStackRemovesTransientsAndStarTrailsNeverDarken()
{
var source = Source(9, configure: o => o with { StartEv = 0, EndEv = 0 });
var input = Input(source, With(stack: new StackSettings { Mode = StackSetting.Median, Length = 5 })) with { Source = new TransientSource(source, 4) };
var (median, _) = await CaptureAsync(input, cancellationToken: _context.Cancellation);
Assert.Equal(9, median.Frames.Count);
using var clean = source.Sequence.Render(4);
Assert.Greater(Psnr(clean, median.Frames[4]), 45);
var stars = Source(12, motion: i => (1.0 * i, 0), configure: o => o with { StarField = true, StartEv = 0, EndEv = 0, StarCount = 60 });
var (trails, _) = await CaptureAsync(Input(stars, With(stack: new StackSettings { Mode = StackSetting.StarTrails, Length = 0 })), cancellationToken: _context.Cancellation);
var luminance = LogLuminance(trails.Frames);
Assert.Monotonic(luminance);
for (var k = 1; k < trails.Frames.Count; k++)
{
var previous = trails.Frames[k - 1].Data;
var current = trails.Frames[k].Data;
for (var i = 0; i < current.Length; i++) Assert.True(current[i] >= previous[i] - 1e-6f, $"pixel {i} darkened at frame {k}");
}
}
[Test]
public async Task PrecomputedAnalysisSkipsTheMeasuringPass()
{
var source = Source(30, flickerEv: 0.2);
var project = With(new ExposureSettings { Deflicker = On(true), HighlightKnee = null });
var measured = await RenderPreparation.PrepareAsync(Input(source, project), cancellationToken: _context.Cancellation);
Assert.Equal(30, measured.Report.MeasuredFrames);
var cached = new PrecomputedAnalysis { LogLuminance = measured.MeasuredLogLuminance };
var decodes = source.Decodes;
var reused = await RenderPreparation.PrepareAsync(Input(source, project) with { Analysis = cached }, cancellationToken: _context.Cancellation);
Assert.Equal(0, reused.Report.MeasuredFrames);
Assert.Equal(decodes, source.Decodes);
Assert.SequenceEqual(measured.ExposureEv, reused.ExposureEv);
var target = measured.TargetLogLuminance();
Assert.Approximately(measured.MeasuredLogLuminance[7] + measured.ExposureEv[7], target[7], 1e-12);
static double[] Steps(double[] v) => [.. v.Zip(v.Skip(1), (a, b) => b - a)];
Assert.Less(Rms(Steps(target)), 0.5 * Rms(Steps(measured.MeasuredLogLuminance)));
var wrongLength = await RenderPreparation.PrepareAsync(Input(source, project) with { Analysis = new PrecomputedAnalysis { LogLuminance = new double[3] } },
cancellationToken: _context.Cancellation);
Assert.Equal(30, wrongLength.Report.MeasuredFrames);
Assert.SequenceEqual(measured.ExposureEv, wrongLength.ExposureEv);
var nothing = await RenderPreparation.PrepareAsync(Input(source), cancellationToken: _context.Cancellation);
Assert.Equal(0, nothing.Report.MeasuredFrames);
Assert.True(nothing.ExposureEv.All(e => e == 0));
}
[Test]
public async Task HeldFramesKeepTheirDurationOnConstantRateOutputs()
{
var source = Source(10, configure: o => o with { TimeShifts = [new SyntheticTimeShift(5, 20)] });
var project = With(timing: new TimingSettings { Mode = On(TimingMode.Adaptive) });
var export = Preset("mjpeg-avi");
var dir = _context.CreateTempDirectory();
var result = await Pipeline().RenderAsync(Input(source, project), Target(dir, export), cancellationToken: _context.Cancellation);
var avi = AviReader.Read(File.ReadAllBytes(result.OutputPath));
Assert.Equal(10, result.FrameCount);
Assert.Equal(12, avi.Frames.Count); // frame 4 lasts three periods (30 s ÷ 10 s)
Assert.Approximately(12 / 25.0, result.DurationSeconds, 1e-9);
}
[Test]
public void SetupReportsGeometryEncoderPlanAndEstimates()
{
var source = Source(48, width: 480, height: 320);
var input = Input(source, With(new ExposureSettings { Deflicker = On(true) }, motion: new MotionSettings { MotionBlur = On(true) }));
var setup = Pipeline().Setup(input, Target("/exports", Preset("gif-preview", 480, 270)));
Assert.True(setup.Encoder.IsReady);
Assert.Equal((480, 270), (setup.Geometry.OutputWidth, setup.Geometry.OutputHeight));
Assert.Equal(48, setup.Plan.Frames.Count);
Assert.True(setup.NeedsPreparation);
var workload = setup.Workload();
Assert.Equal(48, workload.FlowFrames);
Assert.Equal(48, workload.AnalysisFrames);
Assert.Equal(480L * 320, workload.WorkingPixels);
var estimate = setup.Estimate();
Assert.Greater(estimate.Bytes, 0);
Assert.Greater(estimate.Time.TotalSeconds, 0);
}
/// <summary>Adds a bright square to one frame (a passing aircraft light).</summary>
private sealed class TransientSource(IRenderFrameSource inner, int frame) : IRenderFrameSource
{
public int FrameCount => inner.FrameCount;
public int Width => inner.Width;
public int Height => inner.Height;
public async ValueTask<ImageBuffer> GetFrameAsync(int index, int maxLongEdge, DecodePurpose purpose, CancellationToken cancellationToken)
{
var image = await inner.GetFrameAsync(index, maxLongEdge, purpose, cancellationToken);
if (index != frame) return image;
for (var c = 0; c < 3; c++)
{
for (var y = 20; y < 30; y++)
{
for (var x = 40; x < 50; x++) image[c, x, y] = 1;
}
}
return image;
}
}
}
@@ -0,0 +1,68 @@
using Titano.Core.Render.Diagnostics;
using Titano.Core.Video;
using Titano.Testing;
namespace Titano.Core.Tests.Render;
public sealed class SelfTestTests
{
private static readonly string[] Groups = ["plan", "export", "select", "codec", "render", "proc", "robust"];
private readonly TestContext _context;
public SelfTestTests(TestContext context) => _context = context;
[Test]
public void ChecksAreUniqueAndGrouped()
{
Assert.GreaterOrEqual(SelfTest.Checks.Count, 60);
Assert.Equal(SelfTest.Checks.Count, SelfTest.Checks.Select(c => c.Id).Distinct().Count());
Assert.True(SelfTest.Checks.All(c => Groups.Contains(c.Group) && c.Id.StartsWith(c.Group + ".", StringComparison.Ordinal) && c.Description.Length > 0));
Assert.True(Groups.All(g => SelfTest.Checks.Any(c => c.Group == g)));
}
[Test]
public async Task FastGroupsPassAndCleanUp()
{
var work = _context.CreateTempDirectory();
var reported = new List<SelfTestResult>();
var results = await SelfTest.RunAsync(new SelfTestOptions { WorkDirectory = work, Filters = ["plan.", "export.", "select.", "codec."] },
new RenderFixture.Sink<SelfTestResult>(reported.Add), _context.Cancellation);
foreach (var r in results.Where(r => r.Outcome != SelfTestOutcome.Passed)) _context.Log($"{r.Id}: {r.Outcome} {r.Detail}");
Assert.Equal(SelfTest.Checks.Count(c => c.Group is "plan" or "export" or "select" or "codec"), results.Count);
Assert.True(results.All(r => r.Outcome == SelfTestOutcome.Passed));
Assert.SequenceEqual(results.Select(r => r.Id), reported.Select(r => r.Id));
Assert.Empty(Directory.GetFileSystemEntries(work));
}
[Test]
public async Task RenderGroupPassesWithManagedEncoders()
{
var results = await SelfTest.RunAsync(new SelfTestOptions { WorkDirectory = _context.CreateTempDirectory(), Filters = ["render."] }, cancellationToken: _context.Cancellation);
foreach (var r in results) _context.Log($"{r.Id}: {r.Outcome} {r.Detail}");
Assert.Equal(SelfTestOutcome.Skipped, results.Single(r => r.Id == "render.mp4").Outcome);
Assert.True(results.Where(r => r.Id != "render.mp4").All(r => r.Outcome == SelfTestOutcome.Passed));
}
[Test]
public async Task FailuresAreReportedNotThrown()
{
// An "MP4 encoder" that writes nothing: the inspection of its missing file must fail the check, not the run.
var fake = new CapturingEncoderProvider("fake", new EncoderCapability(VideoCodec.H264, "Fake H.264", true, 4096, 4096, false));
var results = await SelfTest.RunAsync(new SelfTestOptions { WorkDirectory = _context.CreateTempDirectory(), Filters = ["render.mp4"], PlatformEncoders = [fake] },
cancellationToken: _context.Cancellation);
var result = results.Single();
Assert.Equal(SelfTestOutcome.Failed, result.Outcome);
Assert.Contains("FileNotFoundException", result.Detail);
}
[Test]
public async Task CancellationStopsTheRunAndCleansUp()
{
var work = _context.CreateTempDirectory();
using var cts = CancellationTokenSource.CreateLinkedTokenSource(_context.Cancellation);
var progress = new RenderFixture.Sink<SelfTestResult>(_ => cts.Cancel());
await Assert.ThrowsAsync<OperationCanceledException>(() => SelfTest.RunAsync(new SelfTestOptions { WorkDirectory = work, Filters = ["plan."] }, progress, cts.Token));
Assert.Empty(Directory.GetFileSystemEntries(work));
}
}