merge: motion and geometry modules
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
30 files changed
+5003
No files matched your search
@@ -0,0 +1,82 @@
|
||||
namespace Titano.Core.Imaging.Geometry;
|
||||
|
||||
/// <summary>
|
||||
/// 2D affine map <c>x' = M11·x + M12·y + Tx</c>, <c>y' = M21·x + M22·y + Ty</c>. Image transforms use
|
||||
/// pixel-centre coordinates: pixel (i, j) sits at (i, j) and an image of width W spans [−0.5, W − 0.5].
|
||||
/// <c>a * b</c> applies <c>b</c> first, then <c>a</c>.
|
||||
/// </summary>
|
||||
public readonly record struct Affine2D(double M11, double M12, double M21, double M22, double Tx, double Ty)
|
||||
{
|
||||
public static Affine2D Identity { get; } = new(1, 0, 0, 1, 0, 0);
|
||||
|
||||
public static Affine2D Translation(double tx, double ty) => new(1, 0, 0, 1, tx, ty);
|
||||
|
||||
public static Affine2D Scaling(double sx, double sy) => new(sx, 0, 0, sy, 0, 0);
|
||||
|
||||
/// <summary>Counter-clockwise rotation in a y-up frame (clockwise on screen, where y points down).</summary>
|
||||
public static Affine2D Rotation(double radians)
|
||||
{
|
||||
var (s, c) = double.SinCos(radians);
|
||||
return new Affine2D(c, -s, s, c, 0, 0);
|
||||
}
|
||||
|
||||
/// <summary>Similarity <c>x' = scale · R(radians) · x + (tx, ty)</c>.</summary>
|
||||
public static Affine2D Similarity(double scale, double radians, double tx, double ty)
|
||||
{
|
||||
var (s, c) = double.SinCos(radians);
|
||||
return new Affine2D(scale * c, -scale * s, scale * s, scale * c, tx, ty);
|
||||
}
|
||||
|
||||
/// <summary>The linear part of <paramref name="map"/> applied about the pivot (cx, cy) instead of the origin.</summary>
|
||||
public static Affine2D About(Affine2D map, double cx, double cy) => Translation(cx, cy) * map * Translation(-cx, -cy);
|
||||
|
||||
public double Determinant => M11 * M22 - M12 * M21;
|
||||
|
||||
/// <summary>Uniform scale of the linear part, √|det|.</summary>
|
||||
public double Scale => double.Sqrt(double.Abs(Determinant));
|
||||
|
||||
/// <summary>Rotation angle (radians) of the closest similarity.</summary>
|
||||
public double Angle => double.Atan2(M21 - M12, M11 + M22);
|
||||
|
||||
public (double X, double Y) Apply(double x, double y) => (M11 * x + M12 * y + Tx, M21 * x + M22 * y + Ty);
|
||||
|
||||
/// <summary>Applies the linear part only (for displacement vectors).</summary>
|
||||
public (double X, double Y) ApplyVector(double x, double y) => (M11 * x + M12 * y, M21 * x + M22 * y);
|
||||
|
||||
/// <summary>This map followed by <paramref name="next"/>.</summary>
|
||||
public Affine2D Then(Affine2D next) => next * this;
|
||||
|
||||
public static Affine2D operator *(Affine2D outer, Affine2D inner) => new(
|
||||
outer.M11 * inner.M11 + outer.M12 * inner.M21,
|
||||
outer.M11 * inner.M12 + outer.M12 * inner.M22,
|
||||
outer.M21 * inner.M11 + outer.M22 * inner.M21,
|
||||
outer.M21 * inner.M12 + outer.M22 * inner.M22,
|
||||
outer.M11 * inner.Tx + outer.M12 * inner.Ty + outer.Tx,
|
||||
outer.M21 * inner.Tx + outer.M22 * inner.Ty + outer.Ty);
|
||||
|
||||
public bool TryInvert(out Affine2D inverse)
|
||||
{
|
||||
var det = Determinant;
|
||||
var norm = double.Abs(M11) + double.Abs(M12) + double.Abs(M21) + double.Abs(M22);
|
||||
if (!(double.Abs(det) > 1e-14 * norm * norm))
|
||||
{
|
||||
inverse = default;
|
||||
return false;
|
||||
}
|
||||
var r = 1 / det;
|
||||
var a = M22 * r;
|
||||
var b = -M12 * r;
|
||||
var c = -M21 * r;
|
||||
var d = M11 * r;
|
||||
inverse = new Affine2D(a, b, c, d, -(a * Tx + b * Ty), -(c * Tx + d * Ty));
|
||||
return true;
|
||||
}
|
||||
|
||||
/// <summary>Inverse map; throws for a singular matrix.</summary>
|
||||
public Affine2D Invert() => TryInvert(out var inverse) ? inverse : throw new InvalidOperationException("The affine map is singular.");
|
||||
|
||||
/// <summary>True when every coefficient is within <paramref name="tolerance"/> of the identity.</summary>
|
||||
public bool IsIdentity(double tolerance = 1e-12) =>
|
||||
double.Abs(M11 - 1) <= tolerance && double.Abs(M12) <= tolerance && double.Abs(M21) <= tolerance
|
||||
&& double.Abs(M22 - 1) <= tolerance && double.Abs(Tx) <= tolerance && double.Abs(Ty) <= tolerance;
|
||||
}
|
||||
@@ -0,0 +1,117 @@
|
||||
using System.Globalization;
|
||||
|
||||
namespace Titano.Core.Imaging.Geometry;
|
||||
|
||||
/// <summary>Axis-aligned rectangle in edge coordinates (a W×H image is <c>(0, 0, W, H)</c>).</summary>
|
||||
public readonly record struct RectD(double X, double Y, double Width, double Height)
|
||||
{
|
||||
public double Right => X + Width;
|
||||
|
||||
public double Bottom => Y + Height;
|
||||
|
||||
public double CenterX => X + Width / 2;
|
||||
|
||||
public double CenterY => Y + Height / 2;
|
||||
|
||||
public static RectD FromSize(double width, double height) => new(0, 0, width, height);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Output aspect ratio: a named preset, a custom W:H, or <see cref="Source"/> (the source frame's own ratio).
|
||||
/// </summary>
|
||||
public readonly record struct AspectRatio
|
||||
{
|
||||
private AspectRatio(int width, int height)
|
||||
{
|
||||
Width = width;
|
||||
Height = height;
|
||||
}
|
||||
|
||||
/// <summary>Ratio numerator; 0 for <see cref="Source"/>.</summary>
|
||||
public int Width { get; }
|
||||
|
||||
/// <summary>Ratio denominator; 0 for <see cref="Source"/>.</summary>
|
||||
public int Height { get; }
|
||||
|
||||
public bool IsSource => Width == 0;
|
||||
|
||||
public static AspectRatio Source => default;
|
||||
|
||||
public static AspectRatio Widescreen { get; } = new(16, 9);
|
||||
|
||||
public static AspectRatio Cinema { get; } = new(21, 9);
|
||||
|
||||
public static AspectRatio Standard { get; } = new(4, 3);
|
||||
|
||||
public static AspectRatio Photo { get; } = new(3, 2);
|
||||
|
||||
public static AspectRatio Square { get; } = new(1, 1);
|
||||
|
||||
public static AspectRatio Vertical { get; } = new(9, 16);
|
||||
|
||||
public static AspectRatio Portrait { get; } = new(4, 5);
|
||||
|
||||
/// <summary>The presets offered to users, <see cref="Source"/> first.</summary>
|
||||
public static IReadOnlyList<AspectRatio> Presets { get; } = [Source, Widescreen, Cinema, Standard, Photo, Square, Vertical, Portrait];
|
||||
|
||||
/// <summary>A custom W:H ratio (reduced to lowest terms).</summary>
|
||||
public static AspectRatio Custom(int width, int height)
|
||||
{
|
||||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(width);
|
||||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(height);
|
||||
var g = Gcd(width, height);
|
||||
return new AspectRatio(width / g, height / g);
|
||||
}
|
||||
|
||||
/// <summary>Width / height, using the source size when this is <see cref="Source"/>.</summary>
|
||||
public double Resolve(double sourceWidth, double sourceHeight) => IsSource ? sourceWidth / sourceHeight : Width / (double)Height;
|
||||
|
||||
/// <summary>Parses "16:9", "16/9" or "source".</summary>
|
||||
public static bool TryParse(string? text, out AspectRatio ratio)
|
||||
{
|
||||
ratio = Source;
|
||||
if (string.IsNullOrWhiteSpace(text)) return false;
|
||||
text = text.Trim();
|
||||
if (text.Equals("source", StringComparison.OrdinalIgnoreCase)) return true;
|
||||
var separator = text.IndexOfAny([':', '/', 'x']);
|
||||
if (separator <= 0
|
||||
|| !int.TryParse(text.AsSpan(0, separator), NumberStyles.None, CultureInfo.InvariantCulture, out var w)
|
||||
|| !int.TryParse(text.AsSpan(separator + 1), NumberStyles.None, CultureInfo.InvariantCulture, out var h)
|
||||
|| w <= 0 || h <= 0)
|
||||
return false;
|
||||
ratio = Custom(w, h);
|
||||
return true;
|
||||
}
|
||||
|
||||
public override string ToString() => IsSource ? "source" : string.Create(CultureInfo.InvariantCulture, $"{Width}:{Height}");
|
||||
|
||||
/// <summary>
|
||||
/// Largest crop of aspect <paramref name="ratio"/> (width / height) inside <paramref name="bounds"/>.
|
||||
/// The offsets place it within the leftover slack: −1 = left/top, 0 = centred, +1 = right/bottom (clamped).
|
||||
/// </summary>
|
||||
public static RectD FitCrop(RectD bounds, double ratio, double offsetX = 0, double offsetY = 0)
|
||||
{
|
||||
if (!(ratio > 0) || double.IsInfinity(ratio)) throw new ArgumentOutOfRangeException(nameof(ratio));
|
||||
if (!(bounds.Width > 0 && bounds.Height > 0)) throw new ArgumentOutOfRangeException(nameof(bounds));
|
||||
double width, height;
|
||||
if (bounds.Width >= bounds.Height * ratio)
|
||||
{
|
||||
height = bounds.Height;
|
||||
width = height * ratio;
|
||||
}
|
||||
else
|
||||
{
|
||||
width = bounds.Width;
|
||||
height = width / ratio;
|
||||
}
|
||||
var fx = (1 + double.Clamp(offsetX, -1, 1)) / 2;
|
||||
var fy = (1 + double.Clamp(offsetY, -1, 1)) / 2;
|
||||
return new RectD(bounds.X + (bounds.Width - width) * fx, bounds.Y + (bounds.Height - height) * fy, width, height);
|
||||
}
|
||||
|
||||
private static int Gcd(int a, int b)
|
||||
{
|
||||
while (b != 0) (a, b) = (b, a % b);
|
||||
return a;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,320 @@
|
||||
using System.Runtime.CompilerServices;
|
||||
using System.Runtime.InteropServices;
|
||||
using System.Runtime.Intrinsics;
|
||||
|
||||
namespace Titano.Core.Imaging.Geometry;
|
||||
|
||||
/// <summary>How samples that fall outside the source are treated.</summary>
|
||||
public enum BorderMode
|
||||
{
|
||||
/// <summary>Replicate the nearest edge pixel.</summary>
|
||||
Clamp,
|
||||
|
||||
/// <summary>Outside is transparent black; the destination carries premultiplied colour and alpha coverage.</summary>
|
||||
Transparent,
|
||||
}
|
||||
|
||||
/// <summary>Crop, aspect, output size and warp of one frame, applied in a single resampling pass.</summary>
|
||||
public sealed record GeometrySettings
|
||||
{
|
||||
/// <summary>Region of the working space to show (edge coordinates); null = the whole frame.</summary>
|
||||
public RectD? Crop { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Output aspect; the largest crop of this aspect inside <see cref="Crop"/> is used. <see cref="AspectRatio.Source"/>
|
||||
/// takes the ratio of the output size when both dimensions are given, else that of the source frame.
|
||||
/// </summary>
|
||||
public AspectRatio Aspect { get; init; } = AspectRatio.Source;
|
||||
|
||||
/// <summary>Placement of the fitted crop within the slack, −1..1 per axis (0 = centred).</summary>
|
||||
public double OffsetX { get; init; }
|
||||
|
||||
public double OffsetY { get; init; }
|
||||
|
||||
/// <summary>Output width in pixels; 0 derives it from the height and aspect, or from the crop.</summary>
|
||||
public int OutputWidth { get; init; }
|
||||
|
||||
/// <summary>Output height in pixels; 0 derives it from the width and aspect, or from the crop.</summary>
|
||||
public int OutputHeight { get; init; }
|
||||
|
||||
/// <summary>Maps working-space pixel-centre coordinates to source pixel-centre coordinates
|
||||
/// (e.g. virtual camera composed with the inverse stabilisation correction).</summary>
|
||||
public Affine2D Warp { get; init; } = Affine2D.Identity;
|
||||
|
||||
public BorderMode Border { get; init; } = BorderMode.Clamp;
|
||||
}
|
||||
|
||||
/// <summary>Resolved geometry: output size and the output→source pixel-centre mapping.</summary>
|
||||
public readonly record struct GeometryPlan(int OutputWidth, int OutputHeight, RectD Crop, Affine2D OutputToSource, BorderMode Border);
|
||||
|
||||
/// <summary>
|
||||
/// Geometry stage: crop rectangle, aspect fit, output size and affine warp composed into one output→source
|
||||
/// map and resampled once with Catmull-Rom (Keys 1981 cubic convolution, a = −0.5). Magnification and 1:1
|
||||
/// use the 4×4 kernel (Vector128 rows in the interior); minification widens the kernel by the footprint
|
||||
/// scale so downsizing does not alias. Rows run in parallel.
|
||||
/// </summary>
|
||||
public static class GeometryStage
|
||||
{
|
||||
private const int ParallelThreshold = 1 << 16;
|
||||
|
||||
/// <summary>Resolves crop, aspect and output size against a source of the given size.</summary>
|
||||
public static GeometryPlan Plan(int sourceWidth, int sourceHeight, GeometrySettings settings)
|
||||
{
|
||||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(sourceWidth);
|
||||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(sourceHeight);
|
||||
ArgumentOutOfRangeException.ThrowIfNegative(settings.OutputWidth);
|
||||
ArgumentOutOfRangeException.ThrowIfNegative(settings.OutputHeight);
|
||||
var bounds = settings.Crop ?? RectD.FromSize(sourceWidth, sourceHeight);
|
||||
var ratio = settings.Aspect.IsSource && settings.OutputWidth > 0 && settings.OutputHeight > 0
|
||||
? settings.OutputWidth / (double)settings.OutputHeight
|
||||
: settings.Aspect.Resolve(sourceWidth, sourceHeight);
|
||||
var crop = AspectRatio.FitCrop(bounds, ratio, settings.OffsetX, settings.OffsetY);
|
||||
|
||||
int width = settings.OutputWidth, height = settings.OutputHeight;
|
||||
if (width == 0 && height == 0)
|
||||
{
|
||||
width = (int)double.Round(crop.Width);
|
||||
height = (int)double.Round(crop.Height);
|
||||
}
|
||||
else if (height == 0)
|
||||
{
|
||||
height = (int)double.Round(width / ratio);
|
||||
}
|
||||
else if (width == 0)
|
||||
{
|
||||
width = (int)double.Round(height * ratio);
|
||||
}
|
||||
width = int.Max(1, width);
|
||||
height = int.Max(1, height);
|
||||
|
||||
// Output pixel centre u ↦ crop edge coordinate X + (u + ½)·Wc/Wout ↦ working pixel centre (−½).
|
||||
var sx = crop.Width / width;
|
||||
var sy = crop.Height / height;
|
||||
var toWorking = new Affine2D(sx, 0, 0, sy, crop.X - 0.5 + 0.5 * sx, crop.Y - 0.5 + 0.5 * sy);
|
||||
return new GeometryPlan(width, height, crop, settings.Warp * toWorking, settings.Border);
|
||||
}
|
||||
|
||||
/// <summary>Plans and renders into a new buffer (4 channels when the border is transparent).</summary>
|
||||
public static ImageBuffer Apply(ImageBuffer source, GeometrySettings settings, CancellationToken cancellationToken = default)
|
||||
{
|
||||
var plan = Plan(source.Width, source.Height, settings);
|
||||
var channels = plan.Border == BorderMode.Transparent ? 4 : source.Channels;
|
||||
var destination = new ImageBuffer(plan.OutputWidth, plan.OutputHeight, channels, clear: false);
|
||||
try
|
||||
{
|
||||
Warp(source, destination, plan.OutputToSource, plan.Border, cancellationToken);
|
||||
return destination;
|
||||
}
|
||||
catch
|
||||
{
|
||||
destination.Dispose();
|
||||
throw;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Fills <paramref name="destination"/> by sampling <paramref name="source"/> at
|
||||
/// <paramref name="outputToSource"/>(x, y) for every destination pixel centre. With
|
||||
/// <see cref="BorderMode.Clamp"/> both buffers have the same channel count; with
|
||||
/// <see cref="BorderMode.Transparent"/> the destination has 4 channels (alpha last, colour premultiplied)
|
||||
/// and the source 3 (opaque) or 4 (premultiplied).
|
||||
/// </summary>
|
||||
public static void Warp(ImageBuffer source, ImageBuffer destination, Affine2D outputToSource, BorderMode border = BorderMode.Clamp, CancellationToken cancellationToken = default)
|
||||
{
|
||||
var transparent = border == BorderMode.Transparent;
|
||||
if (transparent ? destination.Channels != 4 || source.Channels < 3 : destination.Channels != source.Channels)
|
||||
throw new ArgumentException("Destination channels must match the source (Clamp) or be 4 with a colour source (Transparent).", nameof(destination));
|
||||
|
||||
// Source-axis footprint of one output pixel; > 1 means minification and a widened kernel.
|
||||
var footprintX = double.Max(1, double.Hypot(outputToSource.M11, outputToSource.M12));
|
||||
var footprintY = double.Max(1, double.Hypot(outputToSource.M21, outputToSource.M22));
|
||||
var job = new WarpJob(source, destination, outputToSource, transparent, footprintX, footprintY);
|
||||
var rows = destination.Height;
|
||||
if ((long)destination.Width * rows < ParallelThreshold)
|
||||
{
|
||||
for (var y = 0; y < rows; y++)
|
||||
{
|
||||
cancellationToken.ThrowIfCancellationRequested();
|
||||
job.Row(y);
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
Parallel.For(0, rows, new ParallelOptions { CancellationToken = cancellationToken }, job.Row);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Catmull-Rom weights for taps at offsets −1, 0, 1, 2 from floor(x), with t = x − floor(x).</summary>
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
||||
internal static Vector128<float> CatmullRomWeights(float t)
|
||||
{
|
||||
var t2 = t * t;
|
||||
var t3 = t2 * t;
|
||||
return Vector128.Create(
|
||||
0.5f * (-t3 + 2 * t2 - t),
|
||||
0.5f * (3 * t3 - 5 * t2 + 2),
|
||||
0.5f * (-3 * t3 + 4 * t2 + t),
|
||||
0.5f * (t3 - t2));
|
||||
}
|
||||
|
||||
/// <summary>Catmull-Rom kernel value at distance x (support ±2).</summary>
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
||||
internal static double CatmullRom(double x)
|
||||
{
|
||||
x = double.Abs(x);
|
||||
if (x < 1) return (1.5 * x - 2.5) * x * x + 1;
|
||||
if (x < 2) return ((-0.5 * x + 2.5) * x - 4) * x + 2;
|
||||
return 0;
|
||||
}
|
||||
|
||||
private sealed class WarpJob(ImageBuffer source, ImageBuffer destination, Affine2D map, bool transparent, double footprintX, double footprintY)
|
||||
{
|
||||
private readonly int _sw = source.Width;
|
||||
private readonly int _sh = source.Height;
|
||||
private readonly int _colourChannels = transparent ? 3 : source.Channels;
|
||||
private readonly bool _sourceAlpha = transparent && source.Channels == 4;
|
||||
private readonly bool _wide = footprintX > 1 || footprintY > 1;
|
||||
|
||||
public void Row(int y)
|
||||
{
|
||||
if (_wide) WideRow(y);
|
||||
else CubicRow(y);
|
||||
}
|
||||
|
||||
private void CubicRow(int y)
|
||||
{
|
||||
var src = source.Storage;
|
||||
var plane = source.PlaneLength;
|
||||
var dst = destination.Storage;
|
||||
var dplane = destination.PlaneLength;
|
||||
var w = _sw;
|
||||
var h = _sh;
|
||||
var outWidth = destination.Width;
|
||||
var channels = transparent ? 4 : _colourChannels;
|
||||
Span<float> values = stackalloc float[4];
|
||||
for (var x = 0; x < outWidth; x++)
|
||||
{
|
||||
var (sx, sy) = map.Apply(x, y);
|
||||
var fx = double.Floor(sx);
|
||||
var fy = double.Floor(sy);
|
||||
var o = y * outWidth + x;
|
||||
if (!(double.Abs(fx) < 1e9 && double.Abs(fy) < 1e9))
|
||||
{
|
||||
WriteOutside(dst, dplane, o, channels);
|
||||
continue;
|
||||
}
|
||||
var ix = (int)fx;
|
||||
var iy = (int)fy;
|
||||
var wx = CatmullRomWeights((float)(sx - fx));
|
||||
var wy = CatmullRomWeights((float)(sy - fy));
|
||||
if (ix >= 1 && iy >= 1 && ix + 2 < w && iy + 2 < h)
|
||||
{
|
||||
ref var s0 = ref MemoryMarshal.GetArrayDataReference(src);
|
||||
var offset = (nuint)((iy - 1) * w + ix - 1);
|
||||
var stride = (nuint)w;
|
||||
for (var c = 0; c < channels; c++)
|
||||
{
|
||||
if (transparent && c == 3 && !_sourceAlpha)
|
||||
{
|
||||
dst[c * dplane + o] = 1f;
|
||||
continue;
|
||||
}
|
||||
var p = offset + (nuint)(c * plane);
|
||||
var acc = Vector128.LoadUnsafe(ref s0, p) * wy.GetElement(0)
|
||||
+ Vector128.LoadUnsafe(ref s0, p + stride) * wy.GetElement(1)
|
||||
+ Vector128.LoadUnsafe(ref s0, p + 2 * stride) * wy.GetElement(2)
|
||||
+ Vector128.LoadUnsafe(ref s0, p + 3 * stride) * wy.GetElement(3);
|
||||
dst[c * dplane + o] = Vector128.Dot(acc, wx);
|
||||
}
|
||||
continue;
|
||||
}
|
||||
|
||||
// Border: clamp indices, or drop outside taps and accumulate coverage.
|
||||
values.Clear();
|
||||
float coverage = 0;
|
||||
for (var j = 0; j < 4; j++)
|
||||
{
|
||||
var yy = iy - 1 + j;
|
||||
var weightY = wy.GetElement(j);
|
||||
if (transparent && (uint)yy >= (uint)h) continue;
|
||||
yy = int.Clamp(yy, 0, h - 1);
|
||||
for (var i = 0; i < 4; i++)
|
||||
{
|
||||
var xx = ix - 1 + i;
|
||||
if (transparent && (uint)xx >= (uint)w) continue;
|
||||
xx = int.Clamp(xx, 0, w - 1);
|
||||
var weight = weightY * wx.GetElement(i);
|
||||
var s = yy * w + xx;
|
||||
for (var c = 0; c < _colourChannels; c++) values[c] += weight * src[c * plane + s];
|
||||
if (_sourceAlpha) values[3] += weight * src[3 * plane + s];
|
||||
coverage += weight;
|
||||
}
|
||||
}
|
||||
for (var c = 0; c < _colourChannels; c++) dst[c * dplane + o] = values[c];
|
||||
if (transparent) dst[3 * dplane + o] = float.Clamp(_sourceAlpha ? values[3] : coverage, 0f, 1f);
|
||||
}
|
||||
}
|
||||
|
||||
private void WideRow(int y)
|
||||
{
|
||||
var src = source.Storage;
|
||||
var plane = source.PlaneLength;
|
||||
var dst = destination.Storage;
|
||||
var dplane = destination.PlaneLength;
|
||||
var w = _sw;
|
||||
var h = _sh;
|
||||
var outWidth = destination.Width;
|
||||
var channels = transparent ? 4 : _colourChannels;
|
||||
var maxX = (int)double.Ceiling(4 * footprintX) + 2;
|
||||
var maxY = (int)double.Ceiling(4 * footprintY) + 2;
|
||||
Span<double> wxs = maxX <= 256 ? stackalloc double[maxX] : new double[maxX];
|
||||
Span<double> wys = maxY <= 256 ? stackalloc double[maxY] : new double[maxY];
|
||||
Span<double> values = stackalloc double[4];
|
||||
for (var x = 0; x < outWidth; x++)
|
||||
{
|
||||
var (sx, sy) = map.Apply(x, y);
|
||||
var o = y * outWidth + x;
|
||||
if (!(double.Abs(sx) < 1e9 && double.Abs(sy) < 1e9))
|
||||
{
|
||||
WriteOutside(dst, dplane, o, channels);
|
||||
continue;
|
||||
}
|
||||
var x0 = (int)double.Ceiling(sx - 2 * footprintX);
|
||||
var y0 = (int)double.Ceiling(sy - 2 * footprintY);
|
||||
var nx = int.Min(maxX, (int)double.Floor(sx + 2 * footprintX) - x0 + 1);
|
||||
var ny = int.Min(maxY, (int)double.Floor(sy + 2 * footprintY) - y0 + 1);
|
||||
double sumX = 0, sumY = 0;
|
||||
for (var i = 0; i < nx; i++) sumX += wxs[i] = CatmullRom((x0 + i - sx) / footprintX);
|
||||
for (var j = 0; j < ny; j++) sumY += wys[j] = CatmullRom((y0 + j - sy) / footprintY);
|
||||
var norm = 1 / (sumX * sumY);
|
||||
|
||||
values.Clear();
|
||||
double coverage = 0;
|
||||
for (var j = 0; j < ny; j++)
|
||||
{
|
||||
var yy = y0 + j;
|
||||
if (transparent && (uint)yy >= (uint)h) continue;
|
||||
var row = int.Clamp(yy, 0, h - 1) * w;
|
||||
for (var i = 0; i < nx; i++)
|
||||
{
|
||||
var xx = x0 + i;
|
||||
if (transparent && (uint)xx >= (uint)w) continue;
|
||||
var s = row + int.Clamp(xx, 0, w - 1);
|
||||
var weight = wys[j] * wxs[i];
|
||||
for (var c = 0; c < _colourChannels; c++) values[c] += weight * src[c * plane + s];
|
||||
if (_sourceAlpha) values[3] += weight * src[3 * plane + s];
|
||||
coverage += weight;
|
||||
}
|
||||
}
|
||||
for (var c = 0; c < _colourChannels; c++) dst[c * dplane + o] = (float)(values[c] * norm);
|
||||
if (transparent) dst[3 * dplane + o] = (float)double.Clamp((_sourceAlpha ? values[3] : coverage) * norm, 0, 1);
|
||||
}
|
||||
}
|
||||
|
||||
private void WriteOutside(float[] dst, int dplane, int o, int channels)
|
||||
{
|
||||
// Non-finite or absurd coordinates: transparent, or the clamped corner colour for Clamp.
|
||||
for (var c = 0; c < channels; c++) dst[c * dplane + o] = transparent ? 0f : source.Storage[c * source.PlaneLength];
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,84 @@
|
||||
namespace Titano.Core.Motion;
|
||||
|
||||
/// <summary>
|
||||
/// Cubic Bézier timing curve from (0, 0) to (1, 1) with control points (X1, Y1) and (X2, Y2), as in CSS
|
||||
/// <c>cubic-bezier()</c>. X1 and X2 must lie in [0, 1] so time is monotonic; Y values may overshoot.
|
||||
/// </summary>
|
||||
public readonly record struct BezierEasing
|
||||
{
|
||||
public BezierEasing(double x1, double y1, double x2, double y2)
|
||||
{
|
||||
if (!(x1 is >= 0 and <= 1) || !(x2 is >= 0 and <= 1)) throw new ArgumentOutOfRangeException(nameof(x1), "Control-point x must be within [0, 1].");
|
||||
if (!double.IsFinite(y1) || !double.IsFinite(y2)) throw new ArgumentOutOfRangeException(nameof(y1));
|
||||
(X1, Y1, X2, Y2) = (x1, y1, x2, y2);
|
||||
}
|
||||
|
||||
public double X1 { get; }
|
||||
|
||||
public double Y1 { get; }
|
||||
|
||||
public double X2 { get; }
|
||||
|
||||
public double Y2 { get; }
|
||||
|
||||
public static BezierEasing Linear { get; } = new(0, 0, 1, 1);
|
||||
|
||||
/// <summary>Starts at rest, arrives at speed.</summary>
|
||||
public static BezierEasing EaseIn { get; } = new(0.42, 0, 1, 1);
|
||||
|
||||
/// <summary>Starts at speed, arrives at rest.</summary>
|
||||
public static BezierEasing EaseOut { get; } = new(0, 0, 0.58, 1);
|
||||
|
||||
/// <summary>At rest at both ends: chains of these segments are C1-continuous.</summary>
|
||||
public static BezierEasing EaseInOut { get; } = new(0.42, 0, 0.58, 1);
|
||||
|
||||
/// <summary>Eased progress y for time fraction t ∈ [0, 1] (exactly 0 and 1 at the ends).</summary>
|
||||
public double Evaluate(double t)
|
||||
{
|
||||
if (t <= 0) return 0;
|
||||
if (t >= 1) return 1;
|
||||
return Polynomial(Y1, Y2, Parameter(t));
|
||||
}
|
||||
|
||||
/// <summary>Curve parameter s with x(s) = t: Newton's method from s = t, bisection when it stalls.</summary>
|
||||
private double Parameter(double t)
|
||||
{
|
||||
var s = t;
|
||||
for (var i = 0; i < 8; i++)
|
||||
{
|
||||
var error = Polynomial(X1, X2, s) - t;
|
||||
if (double.Abs(error) < 1e-12) return s;
|
||||
var slope = Derivative(X1, X2, s);
|
||||
if (double.Abs(slope) < 1e-9) break;
|
||||
var next = s - error / slope;
|
||||
if (next is < 0 or > 1) break;
|
||||
s = next;
|
||||
}
|
||||
double lo = 0, hi = 1;
|
||||
s = t;
|
||||
for (var i = 0; i < 60 && hi - lo > 1e-14; i++)
|
||||
{
|
||||
if (Polynomial(X1, X2, s) < t) lo = s;
|
||||
else hi = s;
|
||||
s = 0.5 * (lo + hi);
|
||||
}
|
||||
return s;
|
||||
}
|
||||
|
||||
/// <summary>B(s) = 3(1−s)²s·p1 + 3(1−s)s²·p2 + s³ in Horner form.</summary>
|
||||
private static double Polynomial(double p1, double p2, double s)
|
||||
{
|
||||
var c = 3 * p1;
|
||||
var b = 3 * (p2 - p1) - c;
|
||||
var a = 1 - c - b;
|
||||
return ((a * s + b) * s + c) * s;
|
||||
}
|
||||
|
||||
private static double Derivative(double p1, double p2, double s)
|
||||
{
|
||||
var c = 3 * p1;
|
||||
var b = 3 * (p2 - p1) - c;
|
||||
var a = 1 - c - b;
|
||||
return (3 * a * s + 2 * b) * s + c;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,276 @@
|
||||
using System.Buffers;
|
||||
using System.Numerics;
|
||||
using System.Runtime.CompilerServices;
|
||||
using System.Runtime.InteropServices;
|
||||
|
||||
namespace Titano.Core.Motion;
|
||||
|
||||
/// <summary>
|
||||
/// Precomputed complex DFT of one length on split real/imaginary arrays: iterative radix-2
|
||||
/// Cooley–Tukey (1965) for powers of two, Bluestein (1970) chirp-z convolution otherwise.
|
||||
/// Forward uses e^(−2πikn/N); <see cref="Inverse(Span{double}, Span{double})"/> is normalised by 1/N.
|
||||
/// Immutable and thread-safe; obtain shared instances from <see cref="Fourier.Plan"/>.
|
||||
/// </summary>
|
||||
public sealed class FftPlan
|
||||
{
|
||||
private readonly int[]? _bitReverse;
|
||||
// Stage-major twiddles: the stage with half-size h occupies [h − 1, 2h − 1), so SIMD loads are contiguous.
|
||||
private readonly double[]? _twiddleRe, _twiddleIm;
|
||||
private readonly FftPlan? _convolution;
|
||||
private readonly double[]? _chirpRe, _chirpIm;
|
||||
private readonly double[]? _kernelRe, _kernelIm;
|
||||
|
||||
internal FftPlan(int length)
|
||||
{
|
||||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(length);
|
||||
Length = length;
|
||||
IsPowerOfTwo = BitOperations.IsPow2(length);
|
||||
|
||||
// e^(−iπk/N), k = 0..N: the post-processing twiddles of a real transform of length 2N.
|
||||
HalfTwiddleRe = new double[length + 1];
|
||||
HalfTwiddleIm = new double[length + 1];
|
||||
for (var k = 0; k <= length; k++)
|
||||
{
|
||||
var (s, c) = double.SinCos(double.Pi * k / length);
|
||||
HalfTwiddleRe[k] = c;
|
||||
HalfTwiddleIm[k] = -s;
|
||||
}
|
||||
|
||||
if (IsPowerOfTwo)
|
||||
{
|
||||
var bits = BitOperations.Log2((uint)length);
|
||||
_bitReverse = new int[length];
|
||||
for (var i = 0; i < length; i++)
|
||||
_bitReverse[i] = bits == 0 ? 0 : (int)(ReverseBits((uint)i) >> (32 - bits));
|
||||
_twiddleRe = new double[int.Max(1, length - 1)];
|
||||
_twiddleIm = new double[_twiddleRe.Length];
|
||||
for (var h = 1; h < length; h <<= 1)
|
||||
{
|
||||
for (var k = 0; k < h; k++)
|
||||
{
|
||||
var (s, c) = double.SinCos(double.Pi * k / h);
|
||||
_twiddleRe[h - 1 + k] = c;
|
||||
_twiddleIm[h - 1 + k] = -s;
|
||||
}
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
// Bluestein: X_k = c_k · Σ_n (x_n c_n) · conj(c_(k−n)), c_k = e^(−iπk²/N), as a power-of-two circular convolution.
|
||||
var m = (int)BitOperations.RoundUpToPowerOf2((uint)(2 * length - 1));
|
||||
_convolution = Fourier.Plan(m);
|
||||
ScratchLength = 2 * m;
|
||||
_chirpRe = new double[length];
|
||||
_chirpIm = new double[length];
|
||||
_kernelRe = new double[m];
|
||||
_kernelIm = new double[m];
|
||||
for (var k = 0; k < length; k++)
|
||||
{
|
||||
// k² mod 2N keeps the angle argument small and exact for large N.
|
||||
var q = (long)k * k % (2L * length);
|
||||
var (s, c) = double.SinCos(double.Pi * q / length);
|
||||
_chirpRe[k] = c;
|
||||
_chirpIm[k] = -s;
|
||||
_kernelRe[k] = c;
|
||||
_kernelIm[k] = s;
|
||||
if (k > 0)
|
||||
{
|
||||
_kernelRe[m - k] = c;
|
||||
_kernelIm[m - k] = s;
|
||||
}
|
||||
}
|
||||
_convolution.Radix2(_kernelRe, _kernelIm);
|
||||
var scale = 1.0 / m;
|
||||
for (var i = 0; i < m; i++)
|
||||
{
|
||||
_kernelRe[i] *= scale;
|
||||
_kernelIm[i] *= scale;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Transform length N.</summary>
|
||||
public int Length { get; }
|
||||
|
||||
/// <summary>True when the radix-2 path is used.</summary>
|
||||
public bool IsPowerOfTwo { get; }
|
||||
|
||||
/// <summary>Doubles of scratch the scratch-taking overloads need (0 for powers of two).</summary>
|
||||
public int ScratchLength { get; }
|
||||
|
||||
internal double[] HalfTwiddleRe { get; }
|
||||
|
||||
internal double[] HalfTwiddleIm { get; }
|
||||
|
||||
/// <summary>In-place forward DFT. Bluestein lengths rent their scratch from the shared pool.</summary>
|
||||
public void Forward(Span<double> re, Span<double> im)
|
||||
{
|
||||
if (ScratchLength == 0)
|
||||
{
|
||||
Forward(re, im, Span<double>.Empty);
|
||||
return;
|
||||
}
|
||||
var scratch = ArrayPool<double>.Shared.Rent(ScratchLength);
|
||||
try
|
||||
{
|
||||
Forward(re, im, scratch);
|
||||
}
|
||||
finally
|
||||
{
|
||||
ArrayPool<double>.Shared.Return(scratch);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>In-place forward DFT using caller-provided scratch of at least <see cref="ScratchLength"/> doubles.</summary>
|
||||
public void Forward(Span<double> re, Span<double> im, Span<double> scratch)
|
||||
{
|
||||
CheckLengths(re, im, scratch);
|
||||
if (IsPowerOfTwo) Radix2(re, im);
|
||||
else Bluestein(re, im, scratch);
|
||||
}
|
||||
|
||||
/// <summary>In-place inverse DFT, normalised by 1/N.</summary>
|
||||
public void Inverse(Span<double> re, Span<double> im)
|
||||
{
|
||||
// Swapping the real and imaginary parts turns a forward DFT into an unnormalised inverse one.
|
||||
Forward(im, re);
|
||||
Scale(re, im, 1.0 / Length);
|
||||
}
|
||||
|
||||
/// <summary>In-place inverse DFT (normalised by 1/N) using caller-provided scratch.</summary>
|
||||
public void Inverse(Span<double> re, Span<double> im, Span<double> scratch)
|
||||
{
|
||||
Forward(im, re, scratch);
|
||||
Scale(re, im, 1.0 / Length);
|
||||
}
|
||||
|
||||
/// <summary>Unnormalised radix-2 transform; the caller guarantees a power-of-two length.</summary>
|
||||
internal void Radix2(Span<double> re, Span<double> im)
|
||||
{
|
||||
var n = Length;
|
||||
var rev = _bitReverse!;
|
||||
for (var i = 0; i < n; i++)
|
||||
{
|
||||
var j = rev[i];
|
||||
if (j <= i) continue;
|
||||
(re[i], re[j]) = (re[j], re[i]);
|
||||
(im[i], im[j]) = (im[j], im[i]);
|
||||
}
|
||||
|
||||
ref var r0 = ref MemoryMarshal.GetReference(re);
|
||||
ref var i0 = ref MemoryMarshal.GetReference(im);
|
||||
ref var wr0 = ref MemoryMarshal.GetArrayDataReference(_twiddleRe!);
|
||||
ref var wi0 = ref MemoryMarshal.GetArrayDataReference(_twiddleIm!);
|
||||
var vc = Vector<double>.Count;
|
||||
for (var h = 1; h < n; h <<= 1)
|
||||
{
|
||||
ref var wr = ref Unsafe.Add(ref wr0, h - 1);
|
||||
ref var wi = ref Unsafe.Add(ref wi0, h - 1);
|
||||
for (var start = 0; start < n; start += h << 1)
|
||||
{
|
||||
ref var ar = ref Unsafe.Add(ref r0, start);
|
||||
ref var ai = ref Unsafe.Add(ref i0, start);
|
||||
ref var br = ref Unsafe.Add(ref r0, start + h);
|
||||
ref var bi = ref Unsafe.Add(ref i0, start + h);
|
||||
var k = 0;
|
||||
if (Vector.IsHardwareAccelerated && h >= vc)
|
||||
{
|
||||
// h and vc are powers of two, so h is a multiple of vc: no remainder loop needed.
|
||||
for (; k < h; k += vc)
|
||||
{
|
||||
var u = (nuint)k;
|
||||
var cr = Vector.LoadUnsafe(ref wr, u);
|
||||
var ci = Vector.LoadUnsafe(ref wi, u);
|
||||
var xr = Vector.LoadUnsafe(ref br, u);
|
||||
var xi = Vector.LoadUnsafe(ref bi, u);
|
||||
var tr = xr * cr - xi * ci;
|
||||
var ti = xr * ci + xi * cr;
|
||||
var yr = Vector.LoadUnsafe(ref ar, u);
|
||||
var yi = Vector.LoadUnsafe(ref ai, u);
|
||||
(yr - tr).StoreUnsafe(ref br, u);
|
||||
(yi - ti).StoreUnsafe(ref bi, u);
|
||||
(yr + tr).StoreUnsafe(ref ar, u);
|
||||
(yi + ti).StoreUnsafe(ref ai, u);
|
||||
}
|
||||
}
|
||||
for (; k < h; k++)
|
||||
{
|
||||
var cr = Unsafe.Add(ref wr, k);
|
||||
var ci = Unsafe.Add(ref wi, k);
|
||||
ref var xr = ref Unsafe.Add(ref br, k);
|
||||
ref var xi = ref Unsafe.Add(ref bi, k);
|
||||
ref var yr = ref Unsafe.Add(ref ar, k);
|
||||
ref var yi = ref Unsafe.Add(ref ai, k);
|
||||
var tr = xr * cr - xi * ci;
|
||||
var ti = xr * ci + xi * cr;
|
||||
xr = yr - tr;
|
||||
xi = yi - ti;
|
||||
yr += tr;
|
||||
yi += ti;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private void Bluestein(Span<double> re, Span<double> im, Span<double> scratch)
|
||||
{
|
||||
var n = Length;
|
||||
var conv = _convolution!;
|
||||
var m = conv.Length;
|
||||
var ar = scratch[..m];
|
||||
var ai = scratch.Slice(m, m);
|
||||
var cr = _chirpRe!;
|
||||
var ci = _chirpIm!;
|
||||
for (var k = 0; k < n; k++)
|
||||
{
|
||||
ar[k] = re[k] * cr[k] - im[k] * ci[k];
|
||||
ai[k] = re[k] * ci[k] + im[k] * cr[k];
|
||||
}
|
||||
ar[n..].Clear();
|
||||
ai[n..].Clear();
|
||||
|
||||
conv.Radix2(ar, ai);
|
||||
var kr = _kernelRe!;
|
||||
var ki = _kernelIm!;
|
||||
for (var k = 0; k < m; k++)
|
||||
{
|
||||
var xr = ar[k];
|
||||
var xi = ai[k];
|
||||
ar[k] = xr * kr[k] - xi * ki[k];
|
||||
ai[k] = xr * ki[k] + xi * kr[k];
|
||||
}
|
||||
// Unnormalised inverse via the real/imaginary swap; 1/M is folded into the kernel.
|
||||
conv.Radix2(ai, ar);
|
||||
|
||||
for (var k = 0; k < n; k++)
|
||||
{
|
||||
re[k] = ar[k] * cr[k] - ai[k] * ci[k];
|
||||
im[k] = ar[k] * ci[k] + ai[k] * cr[k];
|
||||
}
|
||||
}
|
||||
|
||||
private void CheckLengths(Span<double> re, Span<double> im, Span<double> scratch)
|
||||
{
|
||||
if (re.Length != Length || im.Length != Length)
|
||||
throw new ArgumentException($"Expected {Length} samples, got {re.Length} and {im.Length}.");
|
||||
if (scratch.Length < ScratchLength)
|
||||
throw new ArgumentException($"Scratch must hold {ScratchLength} doubles.", nameof(scratch));
|
||||
}
|
||||
|
||||
private static void Scale(Span<double> re, Span<double> im, double factor)
|
||||
{
|
||||
for (var i = 0; i < re.Length; i++)
|
||||
{
|
||||
re[i] *= factor;
|
||||
im[i] *= factor;
|
||||
}
|
||||
}
|
||||
|
||||
private static uint ReverseBits(uint v)
|
||||
{
|
||||
v = ((v >> 1) & 0x55555555u) | ((v & 0x55555555u) << 1);
|
||||
v = ((v >> 2) & 0x33333333u) | ((v & 0x33333333u) << 2);
|
||||
v = ((v >> 4) & 0x0F0F0F0Fu) | ((v & 0x0F0F0F0Fu) << 4);
|
||||
v = ((v >> 8) & 0x00FF00FFu) | ((v & 0x00FF00FFu) << 8);
|
||||
return (v >> 16) | (v << 16);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,269 @@
|
||||
using System.Buffers;
|
||||
using System.Collections.Concurrent;
|
||||
|
||||
namespace Titano.Core.Motion;
|
||||
|
||||
/// <summary>
|
||||
/// Discrete Fourier transforms on split real/imaginary <see cref="double"/> arrays: cached
|
||||
/// <see cref="FftPlan"/>s (twiddles computed once per length), separable 2D transforms (rows then
|
||||
/// columns, parallel for large images), real-input transforms through the half-length packing trick,
|
||||
/// and analysis windows.
|
||||
/// </summary>
|
||||
public static class Fourier
|
||||
{
|
||||
// Below this many samples a 2D transform is cheaper than the Parallel.For overhead.
|
||||
private const int ParallelThreshold = 1 << 15;
|
||||
|
||||
private static readonly ConcurrentDictionary<int, FftPlan> Plans = new();
|
||||
|
||||
/// <summary>Shared, thread-safe plan for the given length.</summary>
|
||||
public static FftPlan Plan(int length)
|
||||
{
|
||||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(length);
|
||||
return Plans.GetOrAdd(length, static n => new FftPlan(n));
|
||||
}
|
||||
|
||||
/// <summary>In-place forward DFT of any length.</summary>
|
||||
public static void Forward(Span<double> re, Span<double> im) => Plan(re.Length).Forward(re, im);
|
||||
|
||||
/// <summary>In-place inverse DFT of any length, normalised by 1/N.</summary>
|
||||
public static void Inverse(Span<double> re, Span<double> im) => Plan(re.Length).Inverse(re, im);
|
||||
|
||||
/// <summary>In-place forward 2D DFT of a row-major <paramref name="width"/>×<paramref name="height"/> array.</summary>
|
||||
public static void Forward2D(double[] re, double[] im, int width, int height) => Transform2D(re, im, width, height, inverse: false);
|
||||
|
||||
/// <summary>In-place inverse 2D DFT, normalised by 1/(width·height).</summary>
|
||||
public static void Inverse2D(double[] re, double[] im, int width, int height) => Transform2D(re, im, width, height, inverse: true);
|
||||
|
||||
/// <summary>
|
||||
/// Spectrum bins 0..N/2 of a real signal. Even lengths run one complex transform of length N/2
|
||||
/// (even samples as real part, odd samples as imaginary part) and split it with the standard
|
||||
/// post-processing butterflies; odd lengths fall back to a full complex transform.
|
||||
/// </summary>
|
||||
public static void ForwardReal(ReadOnlySpan<double> signal, Span<double> re, Span<double> im)
|
||||
{
|
||||
var n = signal.Length;
|
||||
ArgumentOutOfRangeException.ThrowIfZero(n, nameof(signal));
|
||||
var bins = n / 2 + 1;
|
||||
if (re.Length < bins || im.Length < bins) throw new ArgumentException($"Spectrum spans must hold {bins} bins.");
|
||||
if (n == 1)
|
||||
{
|
||||
re[0] = signal[0];
|
||||
im[0] = 0;
|
||||
return;
|
||||
}
|
||||
if ((n & 1) != 0)
|
||||
{
|
||||
var buffer = ArrayPool<double>.Shared.Rent(2 * n);
|
||||
try
|
||||
{
|
||||
var fr = buffer.AsSpan(0, n);
|
||||
var fi = buffer.AsSpan(n, n);
|
||||
signal.CopyTo(fr);
|
||||
fi.Clear();
|
||||
Plan(n).Forward(fr, fi);
|
||||
fr[..bins].CopyTo(re);
|
||||
fi[..bins].CopyTo(im);
|
||||
}
|
||||
finally
|
||||
{
|
||||
ArrayPool<double>.Shared.Return(buffer);
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
var m = n / 2;
|
||||
for (var j = 0; j < m; j++)
|
||||
{
|
||||
re[j] = signal[2 * j];
|
||||
im[j] = signal[2 * j + 1];
|
||||
}
|
||||
var plan = Plan(m);
|
||||
plan.Forward(re[..m], im[..m]);
|
||||
re[m] = re[0];
|
||||
im[m] = im[0];
|
||||
var wr = plan.HalfTwiddleRe;
|
||||
var wi = plan.HalfTwiddleIm;
|
||||
for (var k = 0; k <= m / 2; k++)
|
||||
{
|
||||
var k2 = m - k;
|
||||
double zr = re[k], zi = im[k], yr = re[k2], yi = im[k2];
|
||||
// E = (Z_k + conj Z_(m−k)) / 2 is the even-sample spectrum, O = (Z_k − conj Z_(m−k)) / 2i the odd one.
|
||||
var er = 0.5 * (zr + yr);
|
||||
var ei = 0.5 * (zi - yi);
|
||||
var or = 0.5 * (zi + yi);
|
||||
var oi = -0.5 * (zr - yr);
|
||||
re[k] = er + wr[k] * or - wi[k] * oi;
|
||||
im[k] = ei + wr[k] * oi + wi[k] * or;
|
||||
// X_(m−k) = conj E + W^(m−k) conj O.
|
||||
re[k2] = er + wr[k2] * or + wi[k2] * oi;
|
||||
im[k2] = -ei + wi[k2] * or - wr[k2] * oi;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Inverse of <see cref="ForwardReal"/>: real signal of length <c>signal.Length</c> from bins 0..N/2.</summary>
|
||||
public static void InverseReal(ReadOnlySpan<double> re, ReadOnlySpan<double> im, Span<double> signal)
|
||||
{
|
||||
var n = signal.Length;
|
||||
ArgumentOutOfRangeException.ThrowIfZero(n, nameof(signal));
|
||||
var bins = n / 2 + 1;
|
||||
if (re.Length < bins || im.Length < bins) throw new ArgumentException($"Spectrum spans must hold {bins} bins.");
|
||||
if (n == 1)
|
||||
{
|
||||
signal[0] = re[0];
|
||||
return;
|
||||
}
|
||||
|
||||
var odd = (n & 1) != 0;
|
||||
var buffer = ArrayPool<double>.Shared.Rent(odd ? 2 * n : n);
|
||||
try
|
||||
{
|
||||
if (odd)
|
||||
{
|
||||
var fr = buffer.AsSpan(0, n);
|
||||
var fi = buffer.AsSpan(n, n);
|
||||
for (var k = 0; k < bins; k++)
|
||||
{
|
||||
fr[k] = re[k];
|
||||
fi[k] = im[k];
|
||||
if (k == 0) continue;
|
||||
fr[n - k] = re[k];
|
||||
fi[n - k] = -im[k];
|
||||
}
|
||||
Plan(n).Inverse(fr, fi);
|
||||
fr.CopyTo(signal);
|
||||
return;
|
||||
}
|
||||
|
||||
var m = n / 2;
|
||||
var zr = buffer.AsSpan(0, m);
|
||||
var zi = buffer.AsSpan(m, m);
|
||||
var plan = Plan(m);
|
||||
var wr = plan.HalfTwiddleRe;
|
||||
var wi = plan.HalfTwiddleIm;
|
||||
for (var k = 0; k < m; k++)
|
||||
{
|
||||
// E = (X_k + conj X_(m−k)) / 2, O = (X_k − conj X_(m−k)) · conj(W^k) / 2, Z = E + iO.
|
||||
double xr = re[k], xi = im[k], yr = re[m - k], yi = -im[m - k];
|
||||
var er = 0.5 * (xr + yr);
|
||||
var ei = 0.5 * (xi + yi);
|
||||
var dr = 0.5 * (xr - yr);
|
||||
var di = 0.5 * (xi - yi);
|
||||
var or = dr * wr[k] + di * wi[k];
|
||||
var oi = di * wr[k] - dr * wi[k];
|
||||
zr[k] = er - oi;
|
||||
zi[k] = ei + or;
|
||||
}
|
||||
plan.Inverse(zr, zi);
|
||||
for (var j = 0; j < m; j++)
|
||||
{
|
||||
signal[2 * j] = zr[j];
|
||||
signal[2 * j + 1] = zi[j];
|
||||
}
|
||||
}
|
||||
finally
|
||||
{
|
||||
ArrayPool<double>.Shared.Return(buffer);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Symmetric Hann window (zero at both ends).</summary>
|
||||
public static void Hann(Span<double> window) => Tukey(window, 1.0);
|
||||
|
||||
/// <summary>
|
||||
/// Symmetric Tukey (tapered cosine) window: flat top with raised-cosine flanks covering a fraction
|
||||
/// <paramref name="alpha"/> of the length; 0 is rectangular, 1 is Hann.
|
||||
/// </summary>
|
||||
public static void Tukey(Span<double> window, double alpha)
|
||||
{
|
||||
ArgumentOutOfRangeException.ThrowIfLessThan(alpha, 0.0);
|
||||
ArgumentOutOfRangeException.ThrowIfGreaterThan(alpha, 1.0);
|
||||
var n = window.Length;
|
||||
if (n == 1 || alpha == 0)
|
||||
{
|
||||
window.Fill(1.0);
|
||||
return;
|
||||
}
|
||||
var half = alpha / 2;
|
||||
for (var i = 0; i < n; i++)
|
||||
{
|
||||
var x = i / (double)(n - 1);
|
||||
var edge = double.Min(x, 1 - x);
|
||||
window[i] = edge >= half ? 1.0 : 0.5 * (1 - double.Cos(double.Pi * edge / half));
|
||||
}
|
||||
}
|
||||
|
||||
private static void Transform2D(double[] re, double[] im, int width, int height, bool inverse)
|
||||
{
|
||||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(width);
|
||||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(height);
|
||||
var length = checked(width * height);
|
||||
if (re.Length < length || im.Length < length) throw new ArgumentException($"Arrays must hold {length} samples.");
|
||||
|
||||
// The inverse is the forward transform with real and imaginary parts swapped, then scaled.
|
||||
var (a, b) = inverse ? (im, re) : (re, im);
|
||||
var rows = Plan(width);
|
||||
var columns = Plan(height);
|
||||
if (length < ParallelThreshold)
|
||||
{
|
||||
var scratch = ArrayPool<double>.Shared.Rent(int.Max(rows.ScratchLength, 2 * height + columns.ScratchLength));
|
||||
try
|
||||
{
|
||||
for (var y = 0; y < height; y++) rows.Forward(a.AsSpan(y * width, width), b.AsSpan(y * width, width), scratch);
|
||||
for (var x = 0; x < width; x++) TransformColumn(a, b, width, height, x, columns, scratch);
|
||||
}
|
||||
finally
|
||||
{
|
||||
ArrayPool<double>.Shared.Return(scratch);
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
Parallel.For(
|
||||
0,
|
||||
height,
|
||||
() => ArrayPool<double>.Shared.Rent(int.Max(1, rows.ScratchLength)),
|
||||
(y, _, scratch) =>
|
||||
{
|
||||
rows.Forward(a.AsSpan(y * width, width), b.AsSpan(y * width, width), scratch);
|
||||
return scratch;
|
||||
},
|
||||
scratch => ArrayPool<double>.Shared.Return(scratch));
|
||||
Parallel.For(
|
||||
0,
|
||||
width,
|
||||
() => ArrayPool<double>.Shared.Rent(2 * height + columns.ScratchLength),
|
||||
(x, _, scratch) =>
|
||||
{
|
||||
TransformColumn(a, b, width, height, x, columns, scratch);
|
||||
return scratch;
|
||||
},
|
||||
scratch => ArrayPool<double>.Shared.Return(scratch));
|
||||
}
|
||||
|
||||
if (!inverse) return;
|
||||
var scale = 1.0 / length;
|
||||
for (var i = 0; i < length; i++)
|
||||
{
|
||||
re[i] *= scale;
|
||||
im[i] *= scale;
|
||||
}
|
||||
}
|
||||
|
||||
private static void TransformColumn(double[] re, double[] im, int width, int height, int x, FftPlan plan, double[] scratch)
|
||||
{
|
||||
var cr = scratch.AsSpan(0, height);
|
||||
var ci = scratch.AsSpan(height, height);
|
||||
for (int y = 0, i = x; y < height; y++, i += width)
|
||||
{
|
||||
cr[y] = re[i];
|
||||
ci[y] = im[i];
|
||||
}
|
||||
plan.Forward(cr, ci, scratch.AsSpan(2 * height));
|
||||
for (int y = 0, i = x; y < height; y++, i += width)
|
||||
{
|
||||
re[i] = cr[y];
|
||||
im[i] = ci[y];
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,150 @@
|
||||
using System.Runtime.Intrinsics;
|
||||
using Titano.Core.Imaging;
|
||||
using Titano.Core.Imaging.Geometry;
|
||||
|
||||
namespace Titano.Core.Motion;
|
||||
|
||||
/// <summary>
|
||||
/// Synthesises a frame at fractional time t between frames A and B from the bidirectional flow. The
|
||||
/// content at output pixel x moves with one of two candidate velocities: A's flow at x, or B's reversed
|
||||
/// flow at x (they differ only near motion boundaries, where each belongs to a different object). Each
|
||||
/// candidate v gives the samples A(x − t·v) and B(x + (1−t)·v); the candidate whose path is forward–backward
|
||||
/// consistent through both frames, |F(A→B)(x − t·v) − v| + |F(B→A)(x + (1−t)·v) + v| smallest, is taken.
|
||||
/// The two Catmull-Rom samples are blended by (1−t, t), each weighted by how well its own flow agrees with v,
|
||||
/// so a sample that is occluded in the other frame or belongs to another object drops out (occlusion
|
||||
/// reasoning after Baker et al. 2011).
|
||||
/// </summary>
|
||||
public sealed class FrameInterpolator : IDisposable
|
||||
{
|
||||
private readonly OpticalFlowEngine _engine;
|
||||
|
||||
public FrameInterpolator(FlowQuality quality = FlowQuality.Best) => _engine = new OpticalFlowEngine(quality);
|
||||
|
||||
/// <summary>Flow disagreement (px) at which a sample's weight halves.</summary>
|
||||
public double OcclusionThreshold { get; init; } = 3.0;
|
||||
|
||||
/// <summary>Computes both flows and writes the frame at <paramref name="t"/> ∈ [0, 1] into <paramref name="destination"/>.</summary>
|
||||
public void Interpolate(ImageBuffer a, ImageBuffer b, double t, ImageBuffer destination, CancellationToken cancellationToken = default)
|
||||
{
|
||||
var (forward, backward) = _engine.ComputeBidirectional(a, b, cancellationToken);
|
||||
using (forward)
|
||||
using (backward)
|
||||
{
|
||||
Synthesize(a, b, forward, backward, t, destination, OcclusionThreshold, cancellationToken);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Frame at <paramref name="t"/> from precomputed flows (forward = A→B, backward = B→A).</summary>
|
||||
public static void Synthesize(ImageBuffer a, ImageBuffer b, MotionField forward, MotionField backward, double t, ImageBuffer destination,
|
||||
double occlusionThreshold = 3.0, CancellationToken cancellationToken = default)
|
||||
{
|
||||
if (b.Width != a.Width || b.Height != a.Height || b.Channels != a.Channels
|
||||
|| destination.Width != a.Width || destination.Height != a.Height || destination.Channels != a.Channels)
|
||||
throw new ArgumentException("Frames and destination must share size and channels.", nameof(destination));
|
||||
if (!(t is >= 0 and <= 1)) throw new ArgumentOutOfRangeException(nameof(t), "t must lie in [0, 1].");
|
||||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(occlusionThreshold);
|
||||
|
||||
var w = a.Width;
|
||||
var h = a.Height;
|
||||
var channels = a.Channels;
|
||||
var tau2 = occlusionThreshold * occlusionThreshold;
|
||||
var dst = destination.Storage;
|
||||
var plane = destination.PlaneLength;
|
||||
|
||||
void Row(int y)
|
||||
{
|
||||
Span<float> va = stackalloc float[4];
|
||||
Span<float> vb = stackalloc float[4];
|
||||
for (var x = 0; x < w; x++)
|
||||
{
|
||||
// Candidate velocities: A's motion at x, and B's motion at x reversed.
|
||||
var (fu, fv) = forward.Sample(x, y);
|
||||
var (bu, bv) = backward.Sample(x, y);
|
||||
var errorF = PathError(forward, backward, x, y, fu, fv, t, out var agreeAF, out var agreeBF);
|
||||
var errorB = PathError(forward, backward, x, y, -bu, -bv, t, out var agreeAB, out var agreeBB);
|
||||
var useForward = errorF <= errorB;
|
||||
double vu = useForward ? fu : -bu, vv = useForward ? fv : -bv;
|
||||
var ax = x - t * vu;
|
||||
var ay = y - t * vv;
|
||||
var bx = x + (1 - t) * vu;
|
||||
var by = y + (1 - t) * vv;
|
||||
|
||||
var wa = (1 - t) * Reliability(useForward ? agreeAF : agreeAB, tau2);
|
||||
var wb = t * Reliability(useForward ? agreeBF : agreeBB, tau2);
|
||||
if (wa + wb < 1e-6)
|
||||
{
|
||||
wa = 1 - t;
|
||||
wb = t;
|
||||
}
|
||||
var norm = 1 / (wa + wb);
|
||||
wa *= norm;
|
||||
wb *= norm;
|
||||
|
||||
var o = y * w + x;
|
||||
va.Clear();
|
||||
vb.Clear();
|
||||
if (wa > 0) CatmullRom(a, ax, ay, va);
|
||||
if (wb > 0) CatmullRom(b, bx, by, vb);
|
||||
for (var c = 0; c < channels; c++) dst[c * plane + o] = (float)(wa * va[c] + wb * vb[c]);
|
||||
}
|
||||
}
|
||||
|
||||
if ((long)w * h < PlaneOps.ParallelThreshold)
|
||||
{
|
||||
for (var y = 0; y < h; y++)
|
||||
{
|
||||
cancellationToken.ThrowIfCancellationRequested();
|
||||
Row(y);
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
Parallel.For(0, h, new ParallelOptions { CancellationToken = cancellationToken }, Row);
|
||||
}
|
||||
}
|
||||
|
||||
public void Dispose() => _engine.Dispose();
|
||||
|
||||
private static double Reliability(double disagreement, double tau2) => tau2 / (tau2 + disagreement * disagreement);
|
||||
|
||||
/// <summary>
|
||||
/// Forward–backward consistency of moving with velocity (vu, vv) through x at time t: how far A's flow at
|
||||
/// the A sample and B's reversed flow at the B sample are from that velocity.
|
||||
/// </summary>
|
||||
private static double PathError(MotionField forward, MotionField backward, int x, int y, double vu, double vv, double t, out double agreeA, out double agreeB)
|
||||
{
|
||||
var (au, av) = forward.Sample(x - t * vu, y - t * vv);
|
||||
var (bu, bv) = backward.Sample(x + (1 - t) * vu, y + (1 - t) * vv);
|
||||
agreeA = double.Hypot(au - vu, av - vv);
|
||||
agreeB = double.Hypot(bu + vu, bv + vv);
|
||||
return agreeA + agreeB;
|
||||
}
|
||||
|
||||
/// <summary>Adds the clamped Catmull-Rom sample of every channel at pixel-centre coordinates to <paramref name="values"/>.</summary>
|
||||
private static void CatmullRom(ImageBuffer image, double x, double y, Span<float> values)
|
||||
{
|
||||
var w = image.Width;
|
||||
var h = image.Height;
|
||||
x = double.Clamp(x, 0, w - 1);
|
||||
y = double.Clamp(y, 0, h - 1);
|
||||
var fx = double.Floor(x);
|
||||
var fy = double.Floor(y);
|
||||
var ix = (int)fx;
|
||||
var iy = (int)fy;
|
||||
var wx = GeometryStage.CatmullRomWeights((float)(x - fx));
|
||||
var wy = GeometryStage.CatmullRomWeights((float)(y - fy));
|
||||
var data = image.Storage;
|
||||
var plane = image.PlaneLength;
|
||||
for (var j = 0; j < 4; j++)
|
||||
{
|
||||
var row = int.Clamp(iy - 1 + j, 0, h - 1) * w;
|
||||
for (var i = 0; i < 4; i++)
|
||||
{
|
||||
var weight = wy.GetElement(j) * wx.GetElement(i);
|
||||
if (weight == 0) continue;
|
||||
var s = row + int.Clamp(ix - 1 + i, 0, w - 1);
|
||||
for (var c = 0; c < image.Channels; c++) values[c] += weight * data[c * plane + s];
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,144 @@
|
||||
using System.Buffers;
|
||||
using System.Numerics;
|
||||
using Titano.Core.Imaging;
|
||||
|
||||
namespace Titano.Core.Motion;
|
||||
|
||||
/// <summary>
|
||||
/// Gaussian pyramid of a single-channel plane (Burt & Adelson 1983): each level is the previous one
|
||||
/// filtered with the 5-tap binomial [1 4 6 4 1]/16 (replicated edges) and decimated by 2, keeping even
|
||||
/// samples, so level-ℓ pixel k sits at full-resolution coordinate k·2^ℓ. Planes are pooled and reused
|
||||
/// by every <see cref="Build(ReadOnlySpan{float})"/>.
|
||||
/// </summary>
|
||||
public sealed class GrayPyramid : IDisposable
|
||||
{
|
||||
private readonly float[][] _levels;
|
||||
private readonly int[] _widths;
|
||||
private readonly int[] _heights;
|
||||
private float[]? _scratch;
|
||||
|
||||
public GrayPyramid(int width, int height, int levels)
|
||||
{
|
||||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(width);
|
||||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(height);
|
||||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(levels);
|
||||
Width = width;
|
||||
Height = height;
|
||||
Levels = levels;
|
||||
_levels = new float[levels][];
|
||||
_widths = new int[levels];
|
||||
_heights = new int[levels];
|
||||
for (var l = 0; l < levels; l++)
|
||||
{
|
||||
_widths[l] = l == 0 ? width : (_widths[l - 1] + 1) / 2;
|
||||
_heights[l] = l == 0 ? height : (_heights[l - 1] + 1) / 2;
|
||||
_levels[l] = ArrayPool<float>.Shared.Rent(_widths[l] * _heights[l]);
|
||||
}
|
||||
_scratch = ArrayPool<float>.Shared.Rent(int.Max(1, _widths[int.Min(1, levels - 1)] * height));
|
||||
}
|
||||
|
||||
public int Width { get; }
|
||||
|
||||
public int Height { get; }
|
||||
|
||||
public int Levels { get; }
|
||||
|
||||
/// <summary>Levels needed until the smaller side would drop below <paramref name="minimumSize"/>, capped.</summary>
|
||||
public static int LevelsFor(int width, int height, int minimumSize = 16, int maximumLevels = 8)
|
||||
{
|
||||
var levels = 1;
|
||||
while (levels < maximumLevels && (int.Min(width, height) + 1) / 2 >= minimumSize)
|
||||
{
|
||||
width = (width + 1) / 2;
|
||||
height = (height + 1) / 2;
|
||||
levels++;
|
||||
}
|
||||
return levels;
|
||||
}
|
||||
|
||||
public int LevelWidth(int level) => _widths[level];
|
||||
|
||||
public int LevelHeight(int level) => _heights[level];
|
||||
|
||||
/// <summary>Row-major samples of one level.</summary>
|
||||
public ReadOnlySpan<float> Level(int level) => LevelArray(level).AsSpan(0, _widths[level] * _heights[level]);
|
||||
|
||||
internal float[] LevelArray(int level)
|
||||
{
|
||||
ObjectDisposedException.ThrowIf(_scratch is null, this);
|
||||
return _levels[level];
|
||||
}
|
||||
|
||||
/// <summary>Builds the pyramid from a plane of <see cref="Width"/>×<see cref="Height"/> samples.</summary>
|
||||
public void Build(ReadOnlySpan<float> plane)
|
||||
{
|
||||
if (plane.Length < Width * Height) throw new ArgumentException("Plane is smaller than the pyramid base.", nameof(plane));
|
||||
plane[..(Width * Height)].CopyTo(LevelArray(0));
|
||||
BuildUpperLevels();
|
||||
}
|
||||
|
||||
/// <summary>Builds the pyramid from the perceptual (sRGB-encoded) luminance of an image.</summary>
|
||||
public void Build(ImageBuffer image)
|
||||
{
|
||||
if (image.Width != Width || image.Height != Height) throw new ArgumentException("Image size differs from the pyramid.", nameof(image));
|
||||
PlaneOps.PerceptualLuminance(image, LevelArray(0).AsSpan(0, Width * Height));
|
||||
BuildUpperLevels();
|
||||
}
|
||||
|
||||
public void Dispose()
|
||||
{
|
||||
var scratch = Interlocked.Exchange(ref _scratch, null);
|
||||
if (scratch is null) return;
|
||||
ArrayPool<float>.Shared.Return(scratch);
|
||||
foreach (var level in _levels) ArrayPool<float>.Shared.Return(level);
|
||||
}
|
||||
|
||||
private void BuildUpperLevels()
|
||||
{
|
||||
for (var l = 1; l < Levels; l++) Downsample(_levels[l - 1], _widths[l - 1], _heights[l - 1], _levels[l], _widths[l], _heights[l], _scratch!);
|
||||
}
|
||||
|
||||
private static void Downsample(float[] source, int width, int height, float[] destination, int halfWidth, int halfHeight, float[] scratch)
|
||||
{
|
||||
// Horizontal: filter and keep even columns (scratch is halfWidth × height).
|
||||
PlaneOps.ForRows(height, width, y =>
|
||||
{
|
||||
var row = source.AsSpan(y * width, width);
|
||||
var output = scratch.AsSpan(y * halfWidth, halfWidth);
|
||||
var last = width - 1;
|
||||
for (var k = 0; k < halfWidth; k++)
|
||||
{
|
||||
var x = 2 * k;
|
||||
output[k] = (row[int.Max(x - 2, 0)] + row[int.Min(x + 2, last)]
|
||||
+ 4 * (row[int.Max(x - 1, 0)] + row[int.Min(x + 1, last)])
|
||||
+ 6 * row[int.Min(x, last)]) * (1f / 16);
|
||||
}
|
||||
});
|
||||
|
||||
// Vertical: five rows combined per output row, vectorised across columns.
|
||||
PlaneOps.ForRows(halfHeight, halfWidth, k =>
|
||||
{
|
||||
var y = 2 * k;
|
||||
var last = height - 1;
|
||||
var r0 = scratch.AsSpan(int.Max(y - 2, 0) * halfWidth, halfWidth);
|
||||
var r1 = scratch.AsSpan(int.Max(y - 1, 0) * halfWidth, halfWidth);
|
||||
var r2 = scratch.AsSpan(int.Min(y, last) * halfWidth, halfWidth);
|
||||
var r3 = scratch.AsSpan(int.Min(y + 1, last) * halfWidth, halfWidth);
|
||||
var r4 = scratch.AsSpan(int.Min(y + 2, last) * halfWidth, halfWidth);
|
||||
var output = destination.AsSpan(k * halfWidth, halfWidth);
|
||||
var i = 0;
|
||||
if (Vector.IsHardwareAccelerated)
|
||||
{
|
||||
var vc = Vector<float>.Count;
|
||||
for (; i <= halfWidth - vc; i += vc)
|
||||
{
|
||||
var sum = new Vector<float>(r0[i..]) + new Vector<float>(r4[i..])
|
||||
+ 4 * (new Vector<float>(r1[i..]) + new Vector<float>(r3[i..]))
|
||||
+ 6 * new Vector<float>(r2[i..]);
|
||||
(sum * (1f / 16)).CopyTo(output[i..]);
|
||||
}
|
||||
}
|
||||
for (; i < halfWidth; i++) output[i] = (r0[i] + r4[i] + 4 * (r1[i] + r3[i]) + 6 * r2[i]) * (1f / 16);
|
||||
});
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,143 @@
|
||||
using Titano.Core.Imaging;
|
||||
|
||||
namespace Titano.Core.Motion;
|
||||
|
||||
/// <summary>Shutter-angle arithmetic for synthetic motion blur.</summary>
|
||||
public static class ShutterAngle
|
||||
{
|
||||
/// <summary>Shutter angle actually used by the camera, 360° × exposure / interval.</summary>
|
||||
public static double FromExposure(double exposureSeconds, double intervalSeconds)
|
||||
{
|
||||
ArgumentOutOfRangeException.ThrowIfNegative(exposureSeconds);
|
||||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(intervalSeconds);
|
||||
return 360.0 * exposureSeconds / intervalSeconds;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Fraction of the frame-to-frame motion to smear so that the real exposure composed with the synthetic
|
||||
/// blur behaves like the target shutter: √(target² − real²) / 360, and 0 when the real angle already
|
||||
/// reaches the target (the blur would only be added on top of blur that is already there).
|
||||
/// </summary>
|
||||
public static double BlurFraction(double targetDegrees, double realDegrees)
|
||||
{
|
||||
ArgumentOutOfRangeException.ThrowIfNegative(targetDegrees);
|
||||
ArgumentOutOfRangeException.ThrowIfNegative(realDegrees);
|
||||
if (realDegrees >= targetDegrees) return 0;
|
||||
return double.Sqrt(targetDegrees * targetDegrees - realDegrees * realDegrees) / 360.0;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Tuning for <see cref="MotionBlurRenderer"/>.</summary>
|
||||
public sealed record MotionBlurOptions
|
||||
{
|
||||
/// <summary>Samples per pixel of blur length (≥ 1 keeps the bilinear taps overlapping).</summary>
|
||||
public double TapsPerPixel { get; init; } = 1.0;
|
||||
|
||||
/// <summary>Upper bound on samples per pixel.</summary>
|
||||
public int MaxTaps { get; init; } = 64;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Motion blur by a gather filter: every output pixel averages bilinear samples of the source along a
|
||||
/// segment centred on it, oriented by its motion vector and as long as the vector times the blur fraction
|
||||
/// (a box shutter: uniform weights, tap count adaptive to the length). Equal weights and bilinear taps
|
||||
/// preserve energy; zero vectors copy the pixel. Rows run in parallel.
|
||||
/// </summary>
|
||||
public sealed class MotionBlurRenderer
|
||||
{
|
||||
private const double MinimumLength = 1e-3;
|
||||
|
||||
public MotionBlurRenderer(MotionBlurOptions? options = null)
|
||||
{
|
||||
Options = options ?? new MotionBlurOptions();
|
||||
ArgumentOutOfRangeException.ThrowIfLessThan(Options.TapsPerPixel, 0.25);
|
||||
ArgumentOutOfRangeException.ThrowIfLessThan(Options.MaxTaps, 2);
|
||||
}
|
||||
|
||||
public MotionBlurOptions Options { get; }
|
||||
|
||||
/// <summary>
|
||||
/// Renders <paramref name="source"/> blurred along <paramref name="motion"/> (frame-to-frame vectors)
|
||||
/// scaled by <paramref name="blurFraction"/> (see <see cref="ShutterAngle.BlurFraction"/>).
|
||||
/// </summary>
|
||||
public void Render(ImageBuffer source, MotionField motion, double blurFraction, ImageBuffer destination, CancellationToken cancellationToken = default)
|
||||
{
|
||||
if (destination.Width != source.Width || destination.Height != source.Height || destination.Channels != source.Channels)
|
||||
throw new ArgumentException("Destination must match the source.", nameof(destination));
|
||||
if (motion.ImageWidth != source.Width || motion.ImageHeight != source.Height)
|
||||
throw new ArgumentException("Motion field describes a different image size.", nameof(motion));
|
||||
ArgumentOutOfRangeException.ThrowIfNegative(blurFraction);
|
||||
if (blurFraction == 0)
|
||||
{
|
||||
source.CopyTo(destination);
|
||||
return;
|
||||
}
|
||||
|
||||
var w = source.Width;
|
||||
var h = source.Height;
|
||||
var channels = source.Channels;
|
||||
var plane = source.PlaneLength;
|
||||
var src = source.Storage;
|
||||
var dst = destination.Storage;
|
||||
var tapsPerPixel = Options.TapsPerPixel;
|
||||
var maxTaps = Options.MaxTaps;
|
||||
|
||||
void Row(int y)
|
||||
{
|
||||
Span<float> sum = stackalloc float[4];
|
||||
for (var x = 0; x < w; x++)
|
||||
{
|
||||
var o = y * w + x;
|
||||
var (mu, mv) = motion.Sample(x, y);
|
||||
var du = mu * blurFraction;
|
||||
var dv = mv * blurFraction;
|
||||
var length = double.Sqrt(du * du + dv * dv);
|
||||
if (length < MinimumLength)
|
||||
{
|
||||
for (var c = 0; c < channels; c++) dst[c * plane + o] = src[c * plane + o];
|
||||
continue;
|
||||
}
|
||||
|
||||
var taps = int.Clamp((int)double.Ceiling(length * tapsPerPixel) + 1, 2, maxTaps);
|
||||
sum.Clear();
|
||||
for (var k = 0; k < taps; k++)
|
||||
{
|
||||
var t = k / (double)(taps - 1) - 0.5;
|
||||
var sx = double.Clamp(x + t * du, 0, w - 1);
|
||||
var sy = double.Clamp(y + t * dv, 0, h - 1);
|
||||
var x0 = int.Min((int)sx, int.Max(w - 2, 0));
|
||||
var y0 = int.Min((int)sy, int.Max(h - 2, 0));
|
||||
var x1 = int.Min(x0 + 1, w - 1);
|
||||
var y1 = int.Min(y0 + 1, h - 1);
|
||||
var fx = (float)(sx - x0);
|
||||
var fy = (float)(sy - y0);
|
||||
var w00 = (1 - fx) * (1 - fy);
|
||||
var w10 = fx * (1 - fy);
|
||||
var w01 = (1 - fx) * fy;
|
||||
var w11 = fx * fy;
|
||||
int i00 = y0 * w + x0, i10 = y0 * w + x1, i01 = y1 * w + x0, i11 = y1 * w + x1;
|
||||
for (var c = 0; c < channels; c++)
|
||||
{
|
||||
var p = c * plane;
|
||||
sum[c] += w00 * src[p + i00] + w10 * src[p + i10] + w01 * src[p + i01] + w11 * src[p + i11];
|
||||
}
|
||||
}
|
||||
var inv = 1f / taps;
|
||||
for (var c = 0; c < channels; c++) dst[c * plane + o] = sum[c] * inv;
|
||||
}
|
||||
}
|
||||
|
||||
if ((long)w * h < PlaneOps.ParallelThreshold)
|
||||
{
|
||||
for (var y = 0; y < h; y++)
|
||||
{
|
||||
cancellationToken.ThrowIfCancellationRequested();
|
||||
Row(y);
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
Parallel.For(0, h, new ParallelOptions { CancellationToken = cancellationToken }, Row);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,154 @@
|
||||
using System.Buffers;
|
||||
|
||||
namespace Titano.Core.Motion;
|
||||
|
||||
/// <summary>Summary of a motion field's vector magnitudes (pixels per frame).</summary>
|
||||
public readonly record struct MotionStatistics(
|
||||
double MeanMagnitude,
|
||||
double MedianMagnitude,
|
||||
double P95Magnitude,
|
||||
double MaxMagnitude,
|
||||
double MeanU,
|
||||
double MeanV,
|
||||
double ReliableFraction);
|
||||
|
||||
/// <summary>
|
||||
/// Dense motion vectors (full-resolution pixels per frame) on a regular grid: node (i, j) describes the
|
||||
/// pixel at (i·Step, j·Step). A vector (u, v) at p means the content at p in the first frame is found at
|
||||
/// p + (u, v) in the second. <see cref="Error"/> holds the forward–backward consistency error in pixels
|
||||
/// (NaN when not checked). Storage is pooled; dispose the field when done.
|
||||
/// </summary>
|
||||
public sealed class MotionField : IDisposable
|
||||
{
|
||||
private float[]? _u;
|
||||
private float[]? _v;
|
||||
private float[]? _error;
|
||||
|
||||
public MotionField(int imageWidth, int imageHeight, int step)
|
||||
{
|
||||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(imageWidth);
|
||||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(imageHeight);
|
||||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(step);
|
||||
ImageWidth = imageWidth;
|
||||
ImageHeight = imageHeight;
|
||||
Step = step;
|
||||
Columns = (imageWidth - 1) / step + 1;
|
||||
Rows = (imageHeight - 1) / step + 1;
|
||||
var n = Columns * Rows;
|
||||
_u = ArrayPool<float>.Shared.Rent(n);
|
||||
_v = ArrayPool<float>.Shared.Rent(n);
|
||||
_error = ArrayPool<float>.Shared.Rent(n);
|
||||
U.Clear();
|
||||
V.Clear();
|
||||
Error.Fill(float.NaN);
|
||||
}
|
||||
|
||||
public int ImageWidth { get; }
|
||||
|
||||
public int ImageHeight { get; }
|
||||
|
||||
/// <summary>Grid spacing in full-resolution pixels.</summary>
|
||||
public int Step { get; }
|
||||
|
||||
public int Columns { get; }
|
||||
|
||||
public int Rows { get; }
|
||||
|
||||
public int Count => Columns * Rows;
|
||||
|
||||
/// <summary>Horizontal components, row-major over the grid.</summary>
|
||||
public Span<float> U => Storage(_u);
|
||||
|
||||
/// <summary>Vertical components, row-major over the grid.</summary>
|
||||
public Span<float> V => Storage(_v);
|
||||
|
||||
/// <summary>Forward–backward error |w(p) + w'(p + w(p))| in pixels; NaN when unchecked.</summary>
|
||||
public Span<float> Error => Storage(_error);
|
||||
|
||||
/// <summary>True when <see cref="Error"/> has been filled by a forward–backward check.</summary>
|
||||
public bool HasConsistency { get; internal set; }
|
||||
|
||||
/// <summary>Bilinearly interpolated vector at a full-resolution pixel-centre position (clamped to the grid).</summary>
|
||||
public (float U, float V) Sample(double x, double y)
|
||||
{
|
||||
var gx = (float)(x / Step);
|
||||
var gy = (float)(y / Step);
|
||||
return (PlaneOps.Bilinear(U, Columns, Rows, gx, gy), PlaneOps.Bilinear(V, Columns, Rows, gx, gy));
|
||||
}
|
||||
|
||||
/// <summary>Bilinearly interpolated forward–backward error (NaN when unchecked).</summary>
|
||||
public float SampleError(double x, double y) =>
|
||||
HasConsistency ? PlaneOps.Bilinear(Error, Columns, Rows, (float)(x / Step), (float)(y / Step)) : float.NaN;
|
||||
|
||||
/// <summary>Counts of vector magnitudes in <paramref name="bins"/> equal bins over [0, max]; larger values land in the last bin.</summary>
|
||||
public int[] MagnitudeHistogram(int bins, double maxMagnitude)
|
||||
{
|
||||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(bins);
|
||||
if (!(maxMagnitude > 0)) throw new ArgumentOutOfRangeException(nameof(maxMagnitude));
|
||||
var histogram = new int[bins];
|
||||
var u = U;
|
||||
var v = V;
|
||||
var scale = bins / maxMagnitude;
|
||||
for (var i = 0; i < u.Length; i++)
|
||||
{
|
||||
var m = double.Sqrt((double)u[i] * u[i] + (double)v[i] * v[i]);
|
||||
histogram[int.Min(bins - 1, (int)(m * scale))]++;
|
||||
}
|
||||
return histogram;
|
||||
}
|
||||
|
||||
/// <summary>Magnitude statistics; vectors with a forward–backward error above <paramref name="reliableError"/> px count as unreliable.</summary>
|
||||
public MotionStatistics Statistics(double reliableError = 1.0)
|
||||
{
|
||||
var n = Count;
|
||||
var magnitudes = ArrayPool<float>.Shared.Rent(n);
|
||||
try
|
||||
{
|
||||
var u = U;
|
||||
var v = V;
|
||||
var error = Error;
|
||||
double sum = 0, su = 0, sv = 0, max = 0;
|
||||
var reliable = 0;
|
||||
for (var i = 0; i < n; i++)
|
||||
{
|
||||
var m = float.Sqrt(u[i] * u[i] + v[i] * v[i]);
|
||||
magnitudes[i] = m;
|
||||
sum += m;
|
||||
su += u[i];
|
||||
sv += v[i];
|
||||
max = double.Max(max, m);
|
||||
if (!HasConsistency || error[i] <= reliableError) reliable++;
|
||||
}
|
||||
var span = magnitudes.AsSpan(0, n);
|
||||
var median = PlaneOps.Median(span);
|
||||
var p95 = PlaneOps.Select(span, int.Min(n - 1, (int)double.Ceiling(0.95 * n) - 1));
|
||||
return new MotionStatistics(sum / n, median, p95, max, su / n, sv / n, reliable / (double)n);
|
||||
}
|
||||
finally
|
||||
{
|
||||
ArrayPool<float>.Shared.Return(magnitudes);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Sets every vector to (u, v).</summary>
|
||||
public void Fill(float u, float v)
|
||||
{
|
||||
U.Fill(u);
|
||||
V.Fill(v);
|
||||
}
|
||||
|
||||
public void Dispose()
|
||||
{
|
||||
Return(ref _u);
|
||||
Return(ref _v);
|
||||
Return(ref _error);
|
||||
}
|
||||
|
||||
private Span<float> Storage(float[]? array) => (array ?? throw new ObjectDisposedException(nameof(MotionField))).AsSpan(0, Count);
|
||||
|
||||
private static void Return(ref float[]? array)
|
||||
{
|
||||
var a = Interlocked.Exchange(ref array, null);
|
||||
if (a is not null) ArrayPool<float>.Shared.Return(a);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,332 @@
|
||||
using System.Buffers;
|
||||
using Titano.Core.Imaging;
|
||||
|
||||
namespace Titano.Core.Motion;
|
||||
|
||||
/// <summary>Speed/quality trade-off of <see cref="OpticalFlowEngine"/>.</summary>
|
||||
public enum FlowQuality
|
||||
{
|
||||
/// <summary>Vectors every 4 px, few iterations: previews and analysis histograms.</summary>
|
||||
Draft,
|
||||
|
||||
/// <summary>Vectors every 2 px: motion blur and analysis.</summary>
|
||||
Balanced,
|
||||
|
||||
/// <summary>Per-pixel vectors, more iterations and a 5×5 median: frame interpolation.</summary>
|
||||
Best,
|
||||
}
|
||||
|
||||
/// <summary>Parameters of the dense pyramidal Lucas–Kanade solver.</summary>
|
||||
public sealed record OpticalFlowOptions
|
||||
{
|
||||
/// <summary>Upper bound on pyramid levels (the coarsest level keeps ≥ 16 px on its short side).</summary>
|
||||
public int MaxLevels { get; init; } = 5;
|
||||
|
||||
/// <summary>Finest level solved; the output grid step is 2^FinestLevel pixels.</summary>
|
||||
public int FinestLevel { get; init; } = 1;
|
||||
|
||||
/// <summary>Warp–solve iterations per level.</summary>
|
||||
public int Iterations { get; init; } = 4;
|
||||
|
||||
/// <summary>Lucas–Kanade integration window radius (box of (2r+1)² samples) at every level.</summary>
|
||||
public int WindowRadius { get; init; } = 3;
|
||||
|
||||
/// <summary>Median filter radius applied to the field after each level (0 = off).</summary>
|
||||
public int MedianRadius { get; init; } = 1;
|
||||
|
||||
/// <summary>Tikhonov term added to the structure tensor diagonal (perceptual luminance² per px²).</summary>
|
||||
public float Regularization { get; init; } = 1e-5f;
|
||||
|
||||
public static OpticalFlowOptions For(FlowQuality quality) => quality switch
|
||||
{
|
||||
FlowQuality.Draft => new OpticalFlowOptions { MaxLevels = 4, FinestLevel = 2, Iterations = 3 },
|
||||
FlowQuality.Balanced => new OpticalFlowOptions(),
|
||||
FlowQuality.Best => new OpticalFlowOptions { MaxLevels = 6, FinestLevel = 0, Iterations = 5, WindowRadius = 4, MedianRadius = 2 },
|
||||
_ => throw new ArgumentOutOfRangeException(nameof(quality)),
|
||||
};
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Dense optical flow by pyramidal Lucas–Kanade (Lucas & Kanade 1981; Bouguet 2000) solved for a window
|
||||
/// around every pixel of each level: both frames get a σ = 1 binomial blur, box-window structure tensors of
|
||||
/// the first frame's gradients are inverted once per level (inverse-compositional form), and each iteration
|
||||
/// warps the second frame by the current flow (bilinear) and re-solves every window with a first-order
|
||||
/// correction for its neighbours' flows; the field is median filtered between levels (Sun, Roth & Black
|
||||
/// 2010). Chosen over Farnebäck polynomial expansion because every step is a separable box filter or a
|
||||
/// per-pixel 2×2 solve that vectorises and parallelises cleanly, with equal sub-pixel accuracy on smooth
|
||||
/// motion. Forward–backward consistency (Sundaram et al. 2010) marks occlusions. One engine holds reusable
|
||||
/// workspaces, so it must not be shared between threads.
|
||||
/// </summary>
|
||||
public sealed class OpticalFlowEngine : IDisposable
|
||||
{
|
||||
private const float MaxUpdate = 2f;
|
||||
|
||||
private GrayPyramid? _first;
|
||||
private GrayPyramid? _second;
|
||||
private float[][] _work = [];
|
||||
private int _capacity;
|
||||
|
||||
public OpticalFlowEngine(OpticalFlowOptions? options = null) => Options = options ?? new OpticalFlowOptions();
|
||||
|
||||
public OpticalFlowEngine(FlowQuality quality) : this(OpticalFlowOptions.For(quality))
|
||||
{
|
||||
}
|
||||
|
||||
public OpticalFlowOptions Options { get; }
|
||||
|
||||
/// <summary>Flow from <paramref name="from"/> to <paramref name="to"/> (perceptual luminance of both).</summary>
|
||||
public MotionField Compute(ImageBuffer from, ImageBuffer to, CancellationToken cancellationToken = default)
|
||||
{
|
||||
BuildPyramids(from, to);
|
||||
return Compute(_first!, _second!, cancellationToken);
|
||||
}
|
||||
|
||||
/// <summary>Flow between two prebuilt pyramids (lets callers reuse each frame's pyramid for two pairs).</summary>
|
||||
public MotionField Compute(GrayPyramid from, GrayPyramid to, CancellationToken cancellationToken = default)
|
||||
{
|
||||
if (from.Width != to.Width || from.Height != to.Height || from.Levels != to.Levels)
|
||||
throw new ArgumentException("Pyramids differ in size or depth.", nameof(to));
|
||||
var coarsest = int.Min(from.Levels, Options.MaxLevels) - 1;
|
||||
var finest = int.Clamp(Options.FinestLevel, 0, coarsest);
|
||||
EnsureWorkspace(from.LevelWidth(finest) * from.LevelHeight(finest));
|
||||
|
||||
float[] u = _work[0], v = _work[1];
|
||||
for (var level = coarsest; level >= finest; level--)
|
||||
{
|
||||
cancellationToken.ThrowIfCancellationRequested();
|
||||
var w = from.LevelWidth(level);
|
||||
var h = from.LevelHeight(level);
|
||||
if (level == coarsest)
|
||||
{
|
||||
Array.Clear(u, 0, w * h);
|
||||
Array.Clear(v, 0, w * h);
|
||||
}
|
||||
else
|
||||
{
|
||||
var (nu, nv) = u == _work[0] ? (_work[2], _work[3]) : (_work[0], _work[1]);
|
||||
Upsample(u, nu, from.LevelWidth(level + 1), from.LevelHeight(level + 1), w, h);
|
||||
Upsample(v, nv, from.LevelWidth(level + 1), from.LevelHeight(level + 1), w, h);
|
||||
(u, v) = (nu, nv);
|
||||
}
|
||||
SolveLevel(from.LevelArray(level), to.LevelArray(level), w, h, u, v, cancellationToken);
|
||||
}
|
||||
|
||||
var step = 1 << finest;
|
||||
var field = new MotionField(from.Width, from.Height, step);
|
||||
var n = field.Count;
|
||||
var fu = field.U;
|
||||
var fv = field.V;
|
||||
for (var i = 0; i < n; i++)
|
||||
{
|
||||
fu[i] = u[i] * step;
|
||||
fv[i] = v[i] * step;
|
||||
}
|
||||
return field;
|
||||
}
|
||||
|
||||
/// <summary>Forward and backward flow with their forward–backward consistency errors filled in.</summary>
|
||||
public (MotionField Forward, MotionField Backward) ComputeBidirectional(ImageBuffer from, ImageBuffer to, CancellationToken cancellationToken = default)
|
||||
{
|
||||
BuildPyramids(from, to);
|
||||
return ComputeBidirectional(_first!, _second!, cancellationToken);
|
||||
}
|
||||
|
||||
/// <inheritdoc cref="ComputeBidirectional(ImageBuffer, ImageBuffer, CancellationToken)"/>
|
||||
public (MotionField Forward, MotionField Backward) ComputeBidirectional(GrayPyramid from, GrayPyramid to, CancellationToken cancellationToken = default)
|
||||
{
|
||||
var forward = Compute(from, to, cancellationToken);
|
||||
try
|
||||
{
|
||||
var backward = Compute(to, from, cancellationToken);
|
||||
CheckConsistency(forward, backward);
|
||||
return (forward, backward);
|
||||
}
|
||||
catch
|
||||
{
|
||||
forward.Dispose();
|
||||
throw;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Fills both fields' <see cref="MotionField.Error"/> with |w(p) + w'(p + w(p))|; vectors leaving the
|
||||
/// frame get +∞ (unverifiable, treated as occluded).
|
||||
/// </summary>
|
||||
public static void CheckConsistency(MotionField forward, MotionField backward)
|
||||
{
|
||||
if (forward.ImageWidth != backward.ImageWidth || forward.ImageHeight != backward.ImageHeight)
|
||||
throw new ArgumentException("Fields describe different image sizes.", nameof(backward));
|
||||
Fill(forward, backward);
|
||||
Fill(backward, forward);
|
||||
forward.HasConsistency = backward.HasConsistency = true;
|
||||
|
||||
static void Fill(MotionField field, MotionField other)
|
||||
{
|
||||
var u = field.U;
|
||||
var v = field.V;
|
||||
var error = field.Error;
|
||||
var maxX = field.ImageWidth - 0.5;
|
||||
var maxY = field.ImageHeight - 0.5;
|
||||
for (var j = 0; j < field.Rows; j++)
|
||||
{
|
||||
for (var i = 0; i < field.Columns; i++)
|
||||
{
|
||||
var k = j * field.Columns + i;
|
||||
var x = i * field.Step + (double)u[k];
|
||||
var y = j * field.Step + (double)v[k];
|
||||
if (x < -0.5 || y < -0.5 || x > maxX || y > maxY)
|
||||
{
|
||||
error[k] = float.PositiveInfinity;
|
||||
continue;
|
||||
}
|
||||
var (bu, bv) = other.Sample(x, y);
|
||||
error[k] = float.Hypot(u[k] + bu, v[k] + bv);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
public void Dispose()
|
||||
{
|
||||
_first?.Dispose();
|
||||
_second?.Dispose();
|
||||
_first = _second = null;
|
||||
foreach (var a in _work) ArrayPool<float>.Shared.Return(a);
|
||||
_work = [];
|
||||
_capacity = 0;
|
||||
}
|
||||
|
||||
private void BuildPyramids(ImageBuffer from, ImageBuffer to)
|
||||
{
|
||||
if (from.Width != to.Width || from.Height != to.Height) throw new ArgumentException("Frames differ in size.", nameof(to));
|
||||
if (_first is null || _first.Width != from.Width || _first.Height != from.Height)
|
||||
{
|
||||
_first?.Dispose();
|
||||
_second?.Dispose();
|
||||
var levels = GrayPyramid.LevelsFor(from.Width, from.Height, 16, Options.MaxLevels);
|
||||
_first = new GrayPyramid(from.Width, from.Height, levels);
|
||||
_second = new GrayPyramid(from.Width, from.Height, levels);
|
||||
}
|
||||
_first.Build(from);
|
||||
_second!.Build(to);
|
||||
}
|
||||
|
||||
private void EnsureWorkspace(int length)
|
||||
{
|
||||
if (length <= _capacity) return;
|
||||
foreach (var a in _work) ArrayPool<float>.Shared.Return(a);
|
||||
// u, v, u', v', Ix, Iy, H11, H12, H22, Bx, By, scratch, smoothed first, smoothed second.
|
||||
_work = new float[14][];
|
||||
for (var i = 0; i < _work.Length; i++) _work[i] = ArrayPool<float>.Shared.Rent(length);
|
||||
_capacity = length;
|
||||
}
|
||||
|
||||
private void SolveLevel(float[] i0, float[] i1, int w, int h, float[] u, float[] v, CancellationToken cancellationToken)
|
||||
{
|
||||
var (spareU, spareV) = u == _work[0] ? (_work[2], _work[3]) : (_work[0], _work[1]);
|
||||
float[] ix = _work[4], iy = _work[5], h11 = _work[6], h12 = _work[7], h22 = _work[8], bx = _work[9], by = _work[10], scratch = _work[11];
|
||||
var radius = Options.WindowRadius;
|
||||
var lambda = Options.Regularization;
|
||||
|
||||
// Central differences under-estimate high-frequency derivatives relative to how the bilinearly warped
|
||||
// frame responds to a flow change (ratio 1/cos πf), which over-shoots the Gauss–Newton step beyond 2×
|
||||
// above f ≈ 1/3 cycles/px and makes the iteration diverge. A σ = 1 blur of both frames removes that
|
||||
// band; being the same translation-invariant filter on both, it does not bias the solution.
|
||||
PlaneOps.Binomial5(i0, _work[12], scratch, w, h);
|
||||
PlaneOps.Binomial5(i1, _work[13], scratch, w, h);
|
||||
i0 = _work[12];
|
||||
i1 = _work[13];
|
||||
|
||||
// Gradients of the first frame and their structure-tensor products.
|
||||
PlaneOps.ForRows(h, w, y =>
|
||||
{
|
||||
var row = y * w;
|
||||
var up = int.Max(y - 1, 0) * w;
|
||||
var down = int.Min(y + 1, h - 1) * w;
|
||||
for (var x = 0; x < w; x++)
|
||||
{
|
||||
var gx = 0.5f * (i0[row + int.Min(x + 1, w - 1)] - i0[row + int.Max(x - 1, 0)]);
|
||||
var gy = 0.5f * (i0[down + x] - i0[up + x]);
|
||||
ix[row + x] = gx;
|
||||
iy[row + x] = gy;
|
||||
h11[row + x] = gx * gx;
|
||||
h12[row + x] = gx * gy;
|
||||
h22[row + x] = gy * gy;
|
||||
}
|
||||
});
|
||||
PlaneOps.BoxFilter(h11, h11, scratch, w, h, radius);
|
||||
PlaneOps.BoxFilter(h12, h12, scratch, w, h, radius);
|
||||
PlaneOps.BoxFilter(h22, h22, scratch, w, h, radius);
|
||||
PlaneOps.ForRows(h, w, y =>
|
||||
{
|
||||
for (int x = 0, k = y * w; x < w; x++, k++)
|
||||
{
|
||||
var a = h11[k] + lambda;
|
||||
var b = h12[k];
|
||||
var c = h22[k] + lambda;
|
||||
var r = 1f / (a * c - b * b);
|
||||
h11[k] = c * r;
|
||||
h12[k] = -b * r;
|
||||
h22[k] = a * r;
|
||||
}
|
||||
});
|
||||
|
||||
for (var iteration = 0; iteration < Options.Iterations; iteration++)
|
||||
{
|
||||
cancellationToken.ThrowIfCancellationRequested();
|
||||
// Each window solves for one flow v: min Σ_y (I1w(y) + g(y)·(v − u(y)) − I0(y))², i.e. the classic
|
||||
// Lucas–Kanade window with a first-order correction for the neighbours' own flows. Unlike the
|
||||
// per-pixel update u −= G⁻¹·box(g·It), this does not feed the current error back through
|
||||
// ill-conditioned (aperture) windows, so it cannot diverge. Samples warped outside the frame
|
||||
// vote for their current flow (It = 0).
|
||||
PlaneOps.ForRows(h, w, y =>
|
||||
{
|
||||
var span = i1.AsSpan(0, w * h);
|
||||
for (int x = 0, k = y * w; x < w; x++, k++)
|
||||
{
|
||||
var px = x + u[k];
|
||||
var py = y + v[k];
|
||||
var it = px >= 0 && py >= 0 && px <= w - 1 && py <= h - 1
|
||||
? PlaneOps.Bilinear(span, w, h, px, py) - i0[k]
|
||||
: 0f;
|
||||
var r = ix[k] * u[k] + iy[k] * v[k] - it;
|
||||
bx[k] = ix[k] * r;
|
||||
by[k] = iy[k] * r;
|
||||
}
|
||||
});
|
||||
PlaneOps.BoxFilter(bx, bx, scratch, w, h, radius);
|
||||
PlaneOps.BoxFilter(by, by, scratch, w, h, radius);
|
||||
PlaneOps.ForRows(h, w, y =>
|
||||
{
|
||||
for (int x = 0, k = y * w; x < w; x++, k++)
|
||||
{
|
||||
// (G + λI)⁻¹ (box(q) + λu): the regulariser keeps textureless windows at their current flow.
|
||||
var qx = bx[k] + lambda * u[k];
|
||||
var qy = by[k] + lambda * v[k];
|
||||
var nu = h11[k] * qx + h12[k] * qy;
|
||||
var nv = h12[k] * qx + h22[k] * qy;
|
||||
u[k] += float.Clamp(nu - u[k], -MaxUpdate, MaxUpdate);
|
||||
v[k] += float.Clamp(nv - v[k], -MaxUpdate, MaxUpdate);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
if (Options.MedianRadius > 0)
|
||||
{
|
||||
PlaneOps.MedianFilter(u, spareU, w, h, Options.MedianRadius);
|
||||
PlaneOps.MedianFilter(v, spareV, w, h, Options.MedianRadius);
|
||||
Array.Copy(spareU, u, w * h);
|
||||
Array.Copy(spareV, v, w * h);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Doubles the resolution and the magnitude of a level's flow (level-ℓ pixel k ↔ level-(ℓ−1) pixel 2k).</summary>
|
||||
private static void Upsample(float[] coarse, float[] fine, int cw, int ch, int w, int h)
|
||||
{
|
||||
PlaneOps.ForRows(h, w, y =>
|
||||
{
|
||||
var span = coarse.AsSpan(0, cw * ch);
|
||||
for (var x = 0; x < w; x++) fine[y * w + x] = 2 * PlaneOps.Bilinear(span, cw, ch, 0.5f * x, 0.5f * y);
|
||||
});
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,40 @@
|
||||
namespace Titano.Core.Motion;
|
||||
|
||||
/// <summary>Smoothing of per-frame series (camera paths).</summary>
|
||||
internal static class PathSmoother
|
||||
{
|
||||
/// <summary>
|
||||
/// Gaussian-weighted local linear regression (degree-1 LOESS with a Gaussian kernel truncated at 3σ):
|
||||
/// each sample is replaced by the value at its own position of a line fitted to its neighbourhood.
|
||||
/// Linear trends (pans) pass unchanged and the ends are not pulled toward the interior, unlike a plain
|
||||
/// Gaussian average. σ ≤ 0 returns a copy.
|
||||
/// </summary>
|
||||
public static double[] LocalLinear(ReadOnlySpan<double> values, double sigma)
|
||||
{
|
||||
var n = values.Length;
|
||||
var result = values.ToArray();
|
||||
if (!(sigma > 0) || n < 2) return result;
|
||||
var radius = (int)double.Ceiling(3 * sigma);
|
||||
Span<double> kernel = radius <= 1024 ? stackalloc double[radius + 1] : new double[radius + 1];
|
||||
for (var d = 0; d <= radius; d++) kernel[d] = double.Exp(-0.5 * d * d / (sigma * sigma));
|
||||
for (var k = 0; k < n; k++)
|
||||
{
|
||||
double s0 = 0, s1 = 0, s2 = 0, t0 = 0, t1 = 0;
|
||||
var lo = int.Max(0, k - radius);
|
||||
var hi = int.Min(n - 1, k + radius);
|
||||
for (var j = lo; j <= hi; j++)
|
||||
{
|
||||
var d = j - k;
|
||||
var w = kernel[int.Abs(d)];
|
||||
s0 += w;
|
||||
s1 += w * d;
|
||||
s2 += w * d * d;
|
||||
t0 += w * values[j];
|
||||
t1 += w * d * values[j];
|
||||
}
|
||||
var det = s0 * s2 - s1 * s1;
|
||||
result[k] = det > 1e-12 * s0 * s0 ? (s2 * t0 - s1 * t1) / det : t0 / s0;
|
||||
}
|
||||
return result;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,273 @@
|
||||
namespace Titano.Core.Motion;
|
||||
|
||||
/// <summary>
|
||||
/// Translation between two patches. <c>moving(x, y) ≈ reference(x − Dx, y − Dy)</c>: content moved by
|
||||
/// (+Dx, +Dy) pixels from the reference to the moving patch. <see cref="Confidence"/> is the peak
|
||||
/// sharpness ratio 1 − second/primary peak, in [0, 1]; <see cref="Peak"/> is the correlation peak height
|
||||
/// (1 for a perfect translation, near 0 for unrelated content).
|
||||
/// </summary>
|
||||
public readonly record struct PhaseCorrelation(double Dx, double Dy, double Confidence, double Peak);
|
||||
|
||||
/// <summary>Tuning for <see cref="PhaseCorrelator"/>.</summary>
|
||||
public sealed record PhaseCorrelatorOptions
|
||||
{
|
||||
/// <summary>Tukey taper fraction of the analysis window (1 = Hann). Suppresses the patch-border discontinuity.</summary>
|
||||
public double WindowTaper { get; init; } = 0.5;
|
||||
|
||||
/// <summary>
|
||||
/// Spatial σ (px) of the Gaussian low-pass applied to the normalised cross-power spectrum. It shapes the
|
||||
/// correlation peak into a sampled Gaussian, which makes the log-parabola sub-pixel fit unbiased, and
|
||||
/// attenuates the noisiest high frequencies.
|
||||
/// </summary>
|
||||
public double PeakSigma { get; init; } = 1.0;
|
||||
|
||||
/// <summary>Largest |shift| searched per axis (px); 0 searches the whole surface.</summary>
|
||||
public int MaxShift { get; init; }
|
||||
|
||||
/// <summary>Default options.</summary>
|
||||
public static PhaseCorrelatorOptions Default { get; } = new();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Kuglin & Hines (1975) phase correlation between two equally sized luminance patches: weighted-mean
|
||||
/// removal, Tukey window, one complex FFT carrying both real patches (reference as real part, moving as
|
||||
/// imaginary part), normalised cross-power spectrum with a relative epsilon and a Gaussian low-pass,
|
||||
/// inverse FFT, integer peak search and a separable Gaussian (log-parabola) sub-pixel fit.
|
||||
/// Holds its working buffers, so one instance must not be used by two threads at once.
|
||||
/// </summary>
|
||||
public sealed class PhaseCorrelator
|
||||
{
|
||||
// Relative regulariser of |cross power|: keeps empty bins from being amplified to unit magnitude.
|
||||
private const double SpectrumEpsilon = 1e-6;
|
||||
|
||||
private readonly double[] _window;
|
||||
private readonly double[] _lowPass;
|
||||
private readonly double[] _re;
|
||||
private readonly double[] _im;
|
||||
private readonly int _maxShiftX;
|
||||
private readonly int _maxShiftY;
|
||||
private readonly int _exclusion;
|
||||
private readonly double _windowSum;
|
||||
|
||||
public PhaseCorrelator(int width, int height, PhaseCorrelatorOptions? options = null)
|
||||
{
|
||||
ArgumentOutOfRangeException.ThrowIfLessThan(width, 4);
|
||||
ArgumentOutOfRangeException.ThrowIfLessThan(height, 4);
|
||||
Options = options ?? PhaseCorrelatorOptions.Default;
|
||||
Width = width;
|
||||
Height = height;
|
||||
var n = width * height;
|
||||
_re = new double[n];
|
||||
_im = new double[n];
|
||||
|
||||
var wxArray = new double[width];
|
||||
var wyArray = new double[height];
|
||||
Fourier.Tukey(wxArray, Options.WindowTaper);
|
||||
Fourier.Tukey(wyArray, Options.WindowTaper);
|
||||
_window = new double[n];
|
||||
for (var y = 0; y < height; y++)
|
||||
{
|
||||
for (var x = 0; x < width; x++)
|
||||
{
|
||||
var w = wyArray[y] * wxArray[x];
|
||||
_window[y * width + x] = w;
|
||||
_windowSum += w;
|
||||
}
|
||||
}
|
||||
|
||||
// Gaussian of spatial σ in the frequency domain: exp(−2π²σ²|f|²), f in cycles per pixel.
|
||||
_lowPass = new double[n];
|
||||
var sigma = Options.PeakSigma;
|
||||
var k = -2.0 * double.Pi * double.Pi * sigma * sigma;
|
||||
for (var v = 0; v < height; v++)
|
||||
{
|
||||
var fy = Signed(v, height) / (double)height;
|
||||
for (var u = 0; u < width; u++)
|
||||
{
|
||||
var fx = Signed(u, width) / (double)width;
|
||||
_lowPass[v * width + u] = sigma > 0 ? double.Exp(k * (fx * fx + fy * fy)) : 1.0;
|
||||
}
|
||||
}
|
||||
_lowPass[0] = 0; // DC carries no shift information.
|
||||
double sum = 0;
|
||||
foreach (var g in _lowPass) sum += g;
|
||||
// Normalise so that a perfect translation produces a unit peak.
|
||||
var norm = n / sum;
|
||||
for (var i = 0; i < n; i++) _lowPass[i] *= norm;
|
||||
|
||||
var limitX = width / 2 - 1;
|
||||
var limitY = height / 2 - 1;
|
||||
_maxShiftX = Options.MaxShift > 0 ? int.Min(Options.MaxShift, limitX) : limitX;
|
||||
_maxShiftY = Options.MaxShift > 0 ? int.Min(Options.MaxShift, limitY) : limitY;
|
||||
_exclusion = int.Max(2, (int)double.Ceiling(3 * double.Max(sigma, 0.5)));
|
||||
}
|
||||
|
||||
public int Width { get; }
|
||||
|
||||
public int Height { get; }
|
||||
|
||||
public PhaseCorrelatorOptions Options { get; }
|
||||
|
||||
/// <summary>Correlates two row-major patches of <see cref="Width"/>×<see cref="Height"/> samples.</summary>
|
||||
public PhaseCorrelation Correlate(ReadOnlySpan<float> reference, ReadOnlySpan<float> moving) =>
|
||||
Correlate(reference, moving, Width, 0, 0);
|
||||
|
||||
/// <summary>
|
||||
/// Correlates the patches at (<paramref name="x0"/>, <paramref name="y0"/>) of two equally sized planes
|
||||
/// with row stride <paramref name="planeWidth"/>.
|
||||
/// </summary>
|
||||
public PhaseCorrelation Correlate(ReadOnlySpan<float> referencePlane, ReadOnlySpan<float> movingPlane, int planeWidth, int x0, int y0)
|
||||
{
|
||||
var w = Width;
|
||||
var h = Height;
|
||||
if (x0 < 0 || y0 < 0 || x0 + w > planeWidth) throw new ArgumentOutOfRangeException(nameof(x0), "Patch outside the plane.");
|
||||
var last = (y0 + h - 1) * planeWidth + x0 + w;
|
||||
if (last > referencePlane.Length || last > movingPlane.Length) throw new ArgumentOutOfRangeException(nameof(y0), "Patch outside the plane.");
|
||||
|
||||
// Window-weighted means, so the windowed patches have exactly zero DC.
|
||||
double ma = 0, mb = 0;
|
||||
for (var y = 0; y < h; y++)
|
||||
{
|
||||
var ra = referencePlane.Slice((y0 + y) * planeWidth + x0, w);
|
||||
var rb = movingPlane.Slice((y0 + y) * planeWidth + x0, w);
|
||||
var win = _window.AsSpan(y * w, w);
|
||||
for (var x = 0; x < w; x++)
|
||||
{
|
||||
ma += win[x] * ra[x];
|
||||
mb += win[x] * rb[x];
|
||||
}
|
||||
}
|
||||
ma /= _windowSum;
|
||||
mb /= _windowSum;
|
||||
for (var y = 0; y < h; y++)
|
||||
{
|
||||
var ra = referencePlane.Slice((y0 + y) * planeWidth + x0, w);
|
||||
var rb = movingPlane.Slice((y0 + y) * planeWidth + x0, w);
|
||||
var o = y * w;
|
||||
for (var x = 0; x < w; x++)
|
||||
{
|
||||
_re[o + x] = (ra[x] - ma) * _window[o + x];
|
||||
_im[o + x] = (rb[x] - mb) * _window[o + x];
|
||||
}
|
||||
}
|
||||
|
||||
Fourier.Forward2D(_re, _im, w, h);
|
||||
CrossPowerSpectrum();
|
||||
Fourier.Inverse2D(_re, _im, w, h);
|
||||
return LocatePeak();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Replaces the packed spectrum Z = A + iB with the normalised, low-passed cross power conj(A)·B / |conj(A)·B|.
|
||||
/// A and B are recovered from Hermitian symmetry: A_k = (Z_k + conj Z_−k)/2, B_k = (Z_k − conj Z_−k)/2i.
|
||||
/// </summary>
|
||||
private void CrossPowerSpectrum()
|
||||
{
|
||||
var w = Width;
|
||||
var h = Height;
|
||||
var re = _re;
|
||||
var im = _im;
|
||||
double magnitudeSum = 0;
|
||||
for (var v = 0; v < h; v++)
|
||||
{
|
||||
var mv = v == 0 ? 0 : h - v;
|
||||
for (var u = 0; u < w; u++)
|
||||
{
|
||||
var i = v * w + u;
|
||||
var j = mv * w + (u == 0 ? 0 : w - u);
|
||||
if (j < i) continue;
|
||||
double zr = re[i], zi = im[i], yr = re[j], yi = im[j];
|
||||
var ar = 0.5 * (zr + yr);
|
||||
var ai = 0.5 * (zi - yi);
|
||||
var br = 0.5 * (zi + yi);
|
||||
var bi = -0.5 * (zr - yr);
|
||||
// conj(A)·B; the mirrored bin holds its conjugate because the correlation is real.
|
||||
var cr = ar * br + ai * bi;
|
||||
var ci = ar * bi - ai * br;
|
||||
re[i] = cr;
|
||||
im[i] = ci;
|
||||
re[j] = cr;
|
||||
im[j] = -ci;
|
||||
var mag = double.Sqrt(cr * cr + ci * ci);
|
||||
magnitudeSum += i == j ? mag : 2 * mag;
|
||||
}
|
||||
}
|
||||
|
||||
var epsilon = SpectrumEpsilon * magnitudeSum / (w * h) + double.Epsilon;
|
||||
var lowPass = _lowPass;
|
||||
for (var i = 0; i < re.Length; i++)
|
||||
{
|
||||
var mag = double.Sqrt(re[i] * re[i] + im[i] * im[i]);
|
||||
var f = lowPass[i] / (mag + epsilon);
|
||||
re[i] *= f;
|
||||
im[i] *= f;
|
||||
}
|
||||
}
|
||||
|
||||
private PhaseCorrelation LocatePeak()
|
||||
{
|
||||
var w = Width;
|
||||
var h = Height;
|
||||
var c = _re;
|
||||
int px = 0, py = 0;
|
||||
var best = double.NegativeInfinity;
|
||||
for (var dy = -_maxShiftY; dy <= _maxShiftY; dy++)
|
||||
{
|
||||
var row = Wrap(dy, h) * w;
|
||||
for (var dx = -_maxShiftX; dx <= _maxShiftX; dx++)
|
||||
{
|
||||
var value = c[row + Wrap(dx, w)];
|
||||
if (value > best)
|
||||
{
|
||||
best = value;
|
||||
px = dx;
|
||||
py = dy;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
double At(int dx, int dy) => c[Wrap(dy, h) * w + Wrap(dx, w)];
|
||||
var fx = SubPixel(At(px - 1, py), best, At(px + 1, py));
|
||||
var fy = SubPixel(At(px, py - 1), best, At(px, py + 1));
|
||||
|
||||
// Second peak: the largest value outside the main lobe (wrap-aware Chebyshev distance).
|
||||
var second = double.NegativeInfinity;
|
||||
for (var dy = -_maxShiftY; dy <= _maxShiftY; dy++)
|
||||
{
|
||||
var row = Wrap(dy, h) * w;
|
||||
var nearY = int.Abs(dy - py) <= _exclusion;
|
||||
for (var dx = -_maxShiftX; dx <= _maxShiftX; dx++)
|
||||
{
|
||||
if (nearY && int.Abs(dx - px) <= _exclusion) continue;
|
||||
var value = c[row + Wrap(dx, w)];
|
||||
if (value > second) second = value;
|
||||
}
|
||||
}
|
||||
|
||||
var confidence = best > 0 ? double.Clamp(1 - double.Max(second, 0) / best, 0, 1) : 0;
|
||||
return new PhaseCorrelation(px + fx, py + fy, confidence, double.Max(best, 0));
|
||||
}
|
||||
|
||||
/// <summary>Vertex of the parabola through log values (exact for a sampled Gaussian), or of the plain
|
||||
/// parabola when a neighbour is not positive; clamped to ±0.5 px.</summary>
|
||||
private static double SubPixel(double left, double centre, double right)
|
||||
{
|
||||
double offset;
|
||||
if (left > 0 && centre > 0 && right > 0)
|
||||
{
|
||||
double l = double.Log(left), c = double.Log(centre), r = double.Log(right);
|
||||
var d = l - 2 * c + r;
|
||||
offset = d < 0 ? 0.5 * (l - r) / d : 0;
|
||||
}
|
||||
else
|
||||
{
|
||||
var d = left - 2 * centre + right;
|
||||
offset = d < 0 ? 0.5 * (left - right) / d : 0;
|
||||
}
|
||||
return double.Clamp(offset, -0.5, 0.5);
|
||||
}
|
||||
|
||||
private static int Signed(int index, int length) => index <= length / 2 ? index : index - length;
|
||||
|
||||
private static int Wrap(int index, int length) => index < 0 ? index + length : index;
|
||||
}
|
||||
@@ -0,0 +1,261 @@
|
||||
using System.Numerics;
|
||||
using System.Runtime.CompilerServices;
|
||||
using Titano.Core.Imaging;
|
||||
|
||||
namespace Titano.Core.Motion;
|
||||
|
||||
/// <summary>Row-parallel kernels on single-channel float planes shared by the motion modules.</summary>
|
||||
internal static class PlaneOps
|
||||
{
|
||||
/// <summary>Below this many pixels per pass the Parallel.For overhead outweighs the work.</summary>
|
||||
public const int ParallelThreshold = 1 << 15;
|
||||
|
||||
/// <summary>Runs <paramref name="body"/> for every row, in parallel when the plane is large.</summary>
|
||||
public static void ForRows(int height, int width, Action<int> body)
|
||||
{
|
||||
if ((long)height * width < ParallelThreshold)
|
||||
{
|
||||
for (var y = 0; y < height; y++) body(y);
|
||||
}
|
||||
else
|
||||
{
|
||||
Parallel.For(0, height, body);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Perceptually uniform luminance (sRGB-encoded Rec.709 Y, 0..1). Motion estimation works on it so that
|
||||
/// shadows carry texture weight comparable to highlights, unlike linear light.
|
||||
/// </summary>
|
||||
public static void PerceptualLuminance(ImageBuffer image, Span<float> destination)
|
||||
{
|
||||
ColorSpace.Luminance(image, destination);
|
||||
for (var i = 0; i < destination.Length; i++) destination[i] = ColorSpace.EncodeFast(destination[i]);
|
||||
}
|
||||
|
||||
/// <summary>Bilinear sample with edge clamping at pixel-centre coordinates.</summary>
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
||||
public static float Bilinear(ReadOnlySpan<float> plane, int width, int height, float x, float y)
|
||||
{
|
||||
x = float.Clamp(x, 0, width - 1);
|
||||
y = float.Clamp(y, 0, height - 1);
|
||||
var x0 = int.Min((int)x, width - 2 < 0 ? 0 : width - 2);
|
||||
var y0 = int.Min((int)y, height - 2 < 0 ? 0 : height - 2);
|
||||
var fx = x - x0;
|
||||
var fy = y - y0;
|
||||
var x1 = int.Min(x0 + 1, width - 1);
|
||||
var y1 = int.Min(y0 + 1, height - 1);
|
||||
var r0 = y0 * width;
|
||||
var r1 = y1 * width;
|
||||
var top = plane[r0 + x0] + (plane[r0 + x1] - plane[r0 + x0]) * fx;
|
||||
var bottom = plane[r1 + x0] + (plane[r1 + x1] - plane[r1 + x0]) * fx;
|
||||
return top + (bottom - top) * fy;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Mean over a (2r+1)² box with replicated edges, by running sums: horizontal pass per row, then a
|
||||
/// vertical pass that keeps Vector<float> column sums for blocks of columns.
|
||||
/// </summary>
|
||||
public static void BoxFilter(float[] source, float[] destination, float[] scratch, int width, int height, int radius)
|
||||
{
|
||||
var inv = 1f / (2 * radius + 1);
|
||||
ForRows(height, width, y =>
|
||||
{
|
||||
var row = source.AsSpan(y * width, width);
|
||||
var output = scratch.AsSpan(y * width, width);
|
||||
float sum = 0;
|
||||
for (var k = -radius; k <= radius; k++) sum += row[int.Clamp(k, 0, width - 1)];
|
||||
for (var x = 0; x < width; x++)
|
||||
{
|
||||
output[x] = sum * inv;
|
||||
sum += row[int.Min(x + radius + 1, width - 1)] - row[int.Max(x - radius, 0)];
|
||||
}
|
||||
});
|
||||
|
||||
const int Block = 256;
|
||||
var blocks = (width + Block - 1) / Block;
|
||||
void Columns(int b)
|
||||
{
|
||||
var x0 = b * Block;
|
||||
var n = int.Min(Block, width - x0);
|
||||
Span<float> acc = stackalloc float[Block];
|
||||
acc = acc[..n];
|
||||
acc.Clear();
|
||||
for (var k = -radius; k <= radius; k++) Add(acc, scratch.AsSpan(int.Clamp(k, 0, height - 1) * width + x0, n), 1f);
|
||||
for (var y = 0; y < height; y++)
|
||||
{
|
||||
Scale(acc, destination.AsSpan(y * width + x0, n), inv);
|
||||
Add(acc, scratch.AsSpan(int.Min(y + radius + 1, height - 1) * width + x0, n), 1f);
|
||||
Add(acc, scratch.AsSpan(int.Max(y - radius, 0) * width + x0, n), -1f);
|
||||
}
|
||||
}
|
||||
if ((long)width * height < ParallelThreshold || blocks == 1)
|
||||
{
|
||||
for (var b = 0; b < blocks; b++) Columns(b);
|
||||
}
|
||||
else
|
||||
{
|
||||
Parallel.For(0, blocks, Columns);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Separable 5-tap binomial [1 4 6 4 1]/16 blur (σ = 1 px) with replicated edges; may run in place.</summary>
|
||||
public static void Binomial5(float[] source, float[] destination, float[] scratch, int width, int height)
|
||||
{
|
||||
ForRows(height, width, y =>
|
||||
{
|
||||
var row = source.AsSpan(y * width, width);
|
||||
var output = scratch.AsSpan(y * width, width);
|
||||
var last = width - 1;
|
||||
for (var x = 0; x < width; x++)
|
||||
{
|
||||
output[x] = (row[int.Max(x - 2, 0)] + row[int.Min(x + 2, last)]
|
||||
+ 4 * (row[int.Max(x - 1, 0)] + row[int.Min(x + 1, last)]) + 6 * row[x]) * (1f / 16);
|
||||
}
|
||||
});
|
||||
ForRows(height, width, y =>
|
||||
{
|
||||
var last = height - 1;
|
||||
var r0 = scratch.AsSpan(int.Max(y - 2, 0) * width, width);
|
||||
var r1 = scratch.AsSpan(int.Max(y - 1, 0) * width, width);
|
||||
var r2 = scratch.AsSpan(y * width, width);
|
||||
var r3 = scratch.AsSpan(int.Min(y + 1, last) * width, width);
|
||||
var r4 = scratch.AsSpan(int.Min(y + 2, last) * width, width);
|
||||
var output = destination.AsSpan(y * width, width);
|
||||
var i = 0;
|
||||
if (Vector.IsHardwareAccelerated)
|
||||
{
|
||||
for (; i <= width - Vector<float>.Count; i += Vector<float>.Count)
|
||||
{
|
||||
var sum = new Vector<float>(r0[i..]) + new Vector<float>(r4[i..])
|
||||
+ 4 * (new Vector<float>(r1[i..]) + new Vector<float>(r3[i..]))
|
||||
+ 6 * new Vector<float>(r2[i..]);
|
||||
(sum * (1f / 16)).CopyTo(output[i..]);
|
||||
}
|
||||
}
|
||||
for (; i < width; i++) output[i] = (r0[i] + r4[i] + 4 * (r1[i] + r3[i]) + 6 * r2[i]) * (1f / 16);
|
||||
});
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Median over a (2r+1)² window with replicated edges. Interior pixels run the vectorised sorting network
|
||||
/// on Vector<float> blocks of neighbouring pixels; borders use scalar selection.
|
||||
/// </summary>
|
||||
public static void MedianFilter(float[] source, float[] destination, int width, int height, int radius)
|
||||
{
|
||||
ForRows(height, width, y =>
|
||||
{
|
||||
var size = 2 * radius + 1;
|
||||
var count = size * size;
|
||||
Span<float> window = stackalloc float[count];
|
||||
var vc = Vector<float>.Count;
|
||||
var interior = Vector.IsHardwareAccelerated && y >= radius && y < height - radius;
|
||||
Span<Vector<float>> lanes = interior ? stackalloc Vector<float>[count] : default;
|
||||
for (var x = 0; x < width;)
|
||||
{
|
||||
if (interior && x >= radius && x + vc + radius <= width)
|
||||
{
|
||||
var n = 0;
|
||||
for (var dy = -radius; dy <= radius; dy++)
|
||||
{
|
||||
var row = (y + dy) * width + x;
|
||||
for (var dx = -radius; dx <= radius; dx++) lanes[n++] = new Vector<float>(source, row + dx);
|
||||
}
|
||||
MedianOfLanes(lanes).CopyTo(destination, y * width + x);
|
||||
x += vc;
|
||||
continue;
|
||||
}
|
||||
var k = 0;
|
||||
for (var dy = -radius; dy <= radius; dy++)
|
||||
{
|
||||
var row = int.Clamp(y + dy, 0, height - 1) * width;
|
||||
for (var dx = -radius; dx <= radius; dx++) window[k++] = source[row + int.Clamp(x + dx, 0, width - 1)];
|
||||
}
|
||||
destination[y * width + x] = Select(window, count / 2);
|
||||
x++;
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Lane-wise exact median of the vectors (mean of the middle pair for even counts) by odd–even
|
||||
/// transposition sort (Habermann 1972): n passes of branch-free min/max; reorders <paramref name="lanes"/>.
|
||||
/// </summary>
|
||||
public static Vector<float> MedianOfLanes(Span<Vector<float>> lanes)
|
||||
{
|
||||
var n = lanes.Length;
|
||||
for (var pass = 0; pass < n; pass++)
|
||||
{
|
||||
for (var k = pass & 1; k + 1 < n; k += 2)
|
||||
{
|
||||
var lo = Vector.Min(lanes[k], lanes[k + 1]);
|
||||
lanes[k + 1] = Vector.Max(lanes[k], lanes[k + 1]);
|
||||
lanes[k] = lo;
|
||||
}
|
||||
}
|
||||
return (n & 1) != 0 ? lanes[n / 2] : (lanes[n / 2 - 1] + lanes[n / 2]) * 0.5f;
|
||||
}
|
||||
|
||||
/// <summary>Exact median (mean of the two middle values for even counts); reorders <paramref name="values"/>.</summary>
|
||||
public static float Median(Span<float> values)
|
||||
{
|
||||
var n = values.Length;
|
||||
var upper = Select(values, n / 2);
|
||||
if ((n & 1) != 0) return upper;
|
||||
// After selection everything left of n/2 is ≤ upper: the lower middle is their maximum.
|
||||
var lower = values[0];
|
||||
for (var i = 1; i < n / 2; i++) lower = float.Max(lower, values[i]);
|
||||
return 0.5f * (lower + upper);
|
||||
}
|
||||
|
||||
/// <summary>k-th smallest value by Wirth/Hoare selection (in place, O(n) expected).</summary>
|
||||
public static float Select(Span<float> values, int k)
|
||||
{
|
||||
int left = 0, right = values.Length - 1;
|
||||
while (left < right)
|
||||
{
|
||||
var pivot = values[k];
|
||||
int i = left, j = right;
|
||||
do
|
||||
{
|
||||
while (values[i] < pivot) i++;
|
||||
while (pivot < values[j]) j--;
|
||||
if (i <= j)
|
||||
{
|
||||
(values[i], values[j]) = (values[j], values[i]);
|
||||
i++;
|
||||
j--;
|
||||
}
|
||||
}
|
||||
while (i <= j);
|
||||
if (j < k) left = i;
|
||||
if (k < i) right = j;
|
||||
}
|
||||
return values[k];
|
||||
}
|
||||
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
||||
private static void Add(Span<float> acc, ReadOnlySpan<float> row, float sign)
|
||||
{
|
||||
var i = 0;
|
||||
if (Vector.IsHardwareAccelerated)
|
||||
{
|
||||
var s = new Vector<float>(sign);
|
||||
for (; i <= acc.Length - Vector<float>.Count; i += Vector<float>.Count)
|
||||
(new Vector<float>(acc[i..]) + new Vector<float>(row[i..]) * s).CopyTo(acc[i..]);
|
||||
}
|
||||
for (; i < acc.Length; i++) acc[i] += row[i] * sign;
|
||||
}
|
||||
|
||||
[MethodImpl(MethodImplOptions.AggressiveInlining)]
|
||||
private static void Scale(ReadOnlySpan<float> acc, Span<float> output, float factor)
|
||||
{
|
||||
var i = 0;
|
||||
if (Vector.IsHardwareAccelerated)
|
||||
{
|
||||
for (; i <= acc.Length - Vector<float>.Count; i += Vector<float>.Count)
|
||||
(new Vector<float>(acc[i..]) * factor).CopyTo(output[i..]);
|
||||
}
|
||||
for (; i < acc.Length; i++) output[i] = acc[i] * factor;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,417 @@
|
||||
using System.Buffers;
|
||||
using System.Numerics;
|
||||
using Titano.Core.Imaging;
|
||||
using Titano.Core.Imaging.Geometry;
|
||||
|
||||
namespace Titano.Core.Motion;
|
||||
|
||||
/// <summary>Tuning for <see cref="Stabilizer"/>.</summary>
|
||||
public sealed record StabilizerOptions
|
||||
{
|
||||
/// <summary>Phase-correlation patch side (power of two recommended); 0 picks min(W, H)/3 rounded down to a power of two, 8..256.</summary>
|
||||
public int PatchSize { get; init; }
|
||||
|
||||
/// <summary>
|
||||
/// Texture gate: minimum gradient energy of a patch (perceptual luminance² per px², measured after a
|
||||
/// 3×3 binomial blur, with the expected contribution of the estimated noise removed).
|
||||
/// </summary>
|
||||
public double TextureThreshold { get; init; } = 1e-5;
|
||||
|
||||
/// <summary>Minimum phase-correlation peak sharpness for a patch vector to be used.</summary>
|
||||
public double MinimumConfidence { get; init; } = 0.3;
|
||||
|
||||
/// <summary>Residual (px) under which a patch vector is an inlier of a similarity hypothesis.</summary>
|
||||
public double InlierThreshold { get; init; } = 1.0;
|
||||
|
||||
/// <summary>Largest plausible frame-to-frame rotation (radians) of a hypothesis.</summary>
|
||||
public double MaxRotation { get; init; } = 0.05;
|
||||
|
||||
/// <summary>Largest plausible frame-to-frame |ln scale| of a hypothesis.</summary>
|
||||
public double MaxScaleChange { get; init; } = 0.05;
|
||||
|
||||
/// <summary>σ (frames) of the Gaussian-weighted local linear regression that smooths the camera path; 0 disables.</summary>
|
||||
public double SmoothingSigma { get; init; } = 12;
|
||||
|
||||
/// <summary>Shake (RMS px) above which stabilisation is recommended (brief §10.3).</summary>
|
||||
public double RecommendThreshold { get; init; } = 0.3;
|
||||
}
|
||||
|
||||
/// <summary>Similarity between consecutive frames: maps previous-frame pixel coordinates to current-frame ones.</summary>
|
||||
public readonly record struct FrameMotion(Affine2D Transform, int ValidPatches, int Inliers)
|
||||
{
|
||||
/// <summary>False when no patch passed the texture and confidence gates (identity assumed).</summary>
|
||||
public bool Estimated => ValidPatches > 0;
|
||||
}
|
||||
|
||||
/// <summary>Outcome of <see cref="Stabilizer.Solve"/>; every transform uses pixel-centre coordinates.</summary>
|
||||
public sealed record StabilizationResult(
|
||||
IReadOnlyList<FrameMotion> Motions,
|
||||
IReadOnlyList<Affine2D> CameraPath,
|
||||
IReadOnlyList<Affine2D> SmoothedPath,
|
||||
IReadOnlyList<Affine2D> Corrections,
|
||||
double ShakeRms,
|
||||
double CropScale,
|
||||
bool Recommended)
|
||||
{
|
||||
/// <summary>Fraction of the frame area lost to the centred crop that hides every correction's borders, 1 − scale².</summary>
|
||||
public double CropCost => 1 - CropScale * CropScale;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Video stabilisation. Per frame: Kuglin–Hines phase correlation of nine patches on a 3×3 grid against the
|
||||
/// previous frame (patches analysed in parallel), texture gating (noise-compensated gradient energy,
|
||||
/// Immerkær 1996 noise estimate; a textureless frame yields no vectors and therefore no motion), then a
|
||||
/// robust similarity fit (exhaustive two-point hypotheses as deterministic RANSAC, plausibility limits,
|
||||
/// weighted least squares on the inliers). <see cref="Solve"/> accumulates the camera path, smooths its
|
||||
/// translation, rotation and log-scale with Gaussian-weighted local linear regression (pans survive
|
||||
/// unchanged), and reports per-frame corrections (smoothed ∘ raw⁻¹), shake RMS and the crop needed to hide
|
||||
/// borders. Memory is two luminance planes plus one small record per frame.
|
||||
/// </summary>
|
||||
public sealed class Stabilizer : IDisposable
|
||||
{
|
||||
// Expected smoothed-gradient energy of unit-variance white noise: 2 · Σ([−1 −2 0 2 1]/8)² · Σ([1 2 1]/4)².
|
||||
private const double NoiseGradientGain = 2 * (10.0 / 64) * (6.0 / 16);
|
||||
|
||||
private readonly PhaseCorrelator[] _correlators;
|
||||
private readonly PhaseCorrelation?[] _results = new PhaseCorrelation?[9];
|
||||
private readonly (int X, int Y)[] _patches;
|
||||
private readonly double[] _previousEnergy;
|
||||
private readonly double[] _currentEnergy;
|
||||
private readonly float[][] _smooth;
|
||||
private readonly Match[] _matches = new Match[9];
|
||||
private readonly List<FrameMotion> _motions = [];
|
||||
private float[]? _previous;
|
||||
private float[]? _current;
|
||||
|
||||
public Stabilizer(int width, int height, StabilizerOptions? options = null)
|
||||
{
|
||||
ArgumentOutOfRangeException.ThrowIfLessThan(width, 16);
|
||||
ArgumentOutOfRangeException.ThrowIfLessThan(height, 16);
|
||||
Options = options ?? new StabilizerOptions();
|
||||
Width = width;
|
||||
Height = height;
|
||||
PatchSize = Options.PatchSize > 0
|
||||
? int.Min(Options.PatchSize, int.Min(width, height))
|
||||
: int.Clamp(1 << BitOperations.Log2((uint)(int.Min(width, height) / 3)), 8, 256);
|
||||
// One correlator and blur buffer per patch so the nine patches are analysed in parallel.
|
||||
_correlators = new PhaseCorrelator[9];
|
||||
_smooth = new float[9][];
|
||||
for (var i = 0; i < 9; i++)
|
||||
{
|
||||
_correlators[i] = new PhaseCorrelator(PatchSize, PatchSize);
|
||||
_smooth[i] = new float[PatchSize * PatchSize];
|
||||
}
|
||||
_patches = new (int, int)[9];
|
||||
for (var j = 0; j < 3; j++)
|
||||
{
|
||||
for (var i = 0; i < 3; i++)
|
||||
{
|
||||
var x = (int)double.Round(width * (2 * i + 1) / 6.0 - PatchSize / 2.0);
|
||||
var y = (int)double.Round(height * (2 * j + 1) / 6.0 - PatchSize / 2.0);
|
||||
_patches[j * 3 + i] = (int.Clamp(x, 0, width - PatchSize), int.Clamp(y, 0, height - PatchSize));
|
||||
}
|
||||
}
|
||||
_previousEnergy = new double[9];
|
||||
_currentEnergy = new double[9];
|
||||
_previous = ArrayPool<float>.Shared.Rent(width * height);
|
||||
_current = ArrayPool<float>.Shared.Rent(width * height);
|
||||
}
|
||||
|
||||
public int Width { get; }
|
||||
|
||||
public int Height { get; }
|
||||
|
||||
public int PatchSize { get; }
|
||||
|
||||
public StabilizerOptions Options { get; }
|
||||
|
||||
public int FrameCount => _motions.Count;
|
||||
|
||||
/// <summary>Adds the next frame (its perceptual luminance is analysed) and returns its motion from the previous frame.</summary>
|
||||
public FrameMotion AddFrame(ImageBuffer frame)
|
||||
{
|
||||
if (frame.Width != Width || frame.Height != Height) throw new ArgumentException("Frame size differs.", nameof(frame));
|
||||
PlaneOps.PerceptualLuminance(frame, CurrentPlane.AsSpan(0, Width * Height));
|
||||
return Analyse();
|
||||
}
|
||||
|
||||
/// <summary>Adds the next frame as a perceptual (sRGB-encoded) luminance plane.</summary>
|
||||
public FrameMotion AddFrame(ReadOnlySpan<float> luminance)
|
||||
{
|
||||
if (luminance.Length < Width * Height) throw new ArgumentException("Plane is smaller than the frame.", nameof(luminance));
|
||||
luminance[..(Width * Height)].CopyTo(CurrentPlane);
|
||||
return Analyse();
|
||||
}
|
||||
|
||||
/// <summary>Smooths the accumulated camera path and derives corrections, shake and crop.</summary>
|
||||
public StabilizationResult Solve()
|
||||
{
|
||||
var n = _motions.Count;
|
||||
if (n == 0) throw new InvalidOperationException("No frames were added.");
|
||||
double cx = (Width - 1) / 2.0, cy = (Height - 1) / 2.0;
|
||||
|
||||
// Camera path C_k: frame-0 coordinates → frame-k coordinates, as (tx, ty, angle, ln scale) about the centre.
|
||||
var path = new Affine2D[n];
|
||||
var parameters = new double[4][];
|
||||
for (var p = 0; p < 4; p++) parameters[p] = new double[n];
|
||||
var current = Affine2D.Identity;
|
||||
for (var k = 0; k < n; k++)
|
||||
{
|
||||
current = _motions[k].Transform * current;
|
||||
path[k] = current;
|
||||
var (x, y) = current.Apply(cx, cy);
|
||||
var angle = current.Angle;
|
||||
if (k > 0) angle += double.Round((parameters[2][k - 1] - angle) / double.Tau) * double.Tau;
|
||||
parameters[0][k] = x - cx;
|
||||
parameters[1][k] = y - cy;
|
||||
parameters[2][k] = angle;
|
||||
parameters[3][k] = double.Log(current.Scale);
|
||||
}
|
||||
|
||||
var smoothed = new Affine2D[n];
|
||||
var corrections = new Affine2D[n];
|
||||
var series = new double[4][];
|
||||
for (var p = 0; p < 4; p++) series[p] = PathSmoother.LocalLinear(parameters[p], Options.SmoothingSigma);
|
||||
for (var k = 0; k < n; k++)
|
||||
{
|
||||
smoothed[k] = Affine2D.Translation(cx + series[0][k], cy + series[1][k])
|
||||
* Affine2D.Similarity(double.Exp(series[3][k]), series[2][k], 0, 0)
|
||||
* Affine2D.Translation(-cx, -cy);
|
||||
var correction = smoothed[k] * path[k].Invert();
|
||||
corrections[k] = correction.IsIdentity(1e-12) ? Affine2D.Identity : correction;
|
||||
}
|
||||
|
||||
var shake = ShakeRms(corrections);
|
||||
var crop = CropScale(corrections);
|
||||
return new StabilizationResult(_motions.ToArray(), path, smoothed, corrections, shake, crop, shake > Options.RecommendThreshold);
|
||||
}
|
||||
|
||||
public void Dispose()
|
||||
{
|
||||
var previous = Interlocked.Exchange(ref _previous, null);
|
||||
var current = Interlocked.Exchange(ref _current, null);
|
||||
if (previous is not null) ArrayPool<float>.Shared.Return(previous);
|
||||
if (current is not null) ArrayPool<float>.Shared.Return(current);
|
||||
}
|
||||
|
||||
private float[] CurrentPlane => _current ?? throw new ObjectDisposedException(nameof(Stabilizer));
|
||||
|
||||
private FrameMotion Analyse()
|
||||
{
|
||||
var current = CurrentPlane;
|
||||
var first = _motions.Count == 0;
|
||||
var previous = _previous!;
|
||||
Parallel.For(0, 9, i =>
|
||||
{
|
||||
var (x0, y0) = _patches[i];
|
||||
_currentEnergy[i] = TextureEnergy(current, x0, y0, _smooth[i]);
|
||||
_results[i] = first || double.Min(_previousEnergy[i], _currentEnergy[i]) < Options.TextureThreshold
|
||||
? null
|
||||
: _correlators[i].Correlate(previous, current, Width, x0, y0);
|
||||
});
|
||||
|
||||
// Gathered in patch order, so the fit does not depend on thread scheduling.
|
||||
var count = 0;
|
||||
var half = (PatchSize - 1) / 2.0;
|
||||
for (var i = 0; i < 9; i++)
|
||||
{
|
||||
if (_results[i] is not { } r || r.Confidence < Options.MinimumConfidence) continue;
|
||||
var (x0, y0) = _patches[i];
|
||||
_matches[count++] = new Match(x0 + half, y0 + half, x0 + half + r.Dx, y0 + half + r.Dy, r.Confidence);
|
||||
}
|
||||
var motion = first ? new FrameMotion(Affine2D.Identity, 0, 0) : FitSimilarity(_matches.AsSpan(0, count));
|
||||
|
||||
_motions.Add(motion);
|
||||
(_previous, _current) = (_current, _previous);
|
||||
_currentEnergy.CopyTo(_previousEnergy, 0);
|
||||
return motion;
|
||||
}
|
||||
|
||||
/// <summary>Noise-compensated mean squared gradient of the blurred patch.</summary>
|
||||
private double TextureEnergy(float[] plane, int x0, int y0, float[] smooth)
|
||||
{
|
||||
var p = PatchSize;
|
||||
var w = Width;
|
||||
double laplacian = 0;
|
||||
for (var y = 1; y < p - 1; y++)
|
||||
{
|
||||
var row = (y0 + y) * w + x0;
|
||||
for (var x = 1; x < p - 1; x++)
|
||||
{
|
||||
var c = row + x;
|
||||
float a = plane[c - w - 1], b = plane[c - w], d = plane[c - w + 1];
|
||||
float e = plane[c - 1], f = plane[c], g = plane[c + 1];
|
||||
float h = plane[c + w - 1], i = plane[c + w], j = plane[c + w + 1];
|
||||
smooth[y * p + x] = (a + d + h + j + 2 * (b + e + g + i) + 4 * f) * (1f / 16);
|
||||
laplacian += float.Abs(a + d + h + j - 2 * (b + e + g + i) + 4 * f);
|
||||
}
|
||||
}
|
||||
var sigma = double.Sqrt(double.Pi / 2) * laplacian / (6.0 * (p - 2) * (p - 2));
|
||||
|
||||
double energy = 0;
|
||||
var samples = 0;
|
||||
for (var y = 2; y < p - 2; y++)
|
||||
{
|
||||
for (var x = 2; x < p - 2; x++)
|
||||
{
|
||||
var k = y * p + x;
|
||||
var gx = 0.5 * (smooth[k + 1] - smooth[k - 1]);
|
||||
var gy = 0.5 * (smooth[k + p] - smooth[k - p]);
|
||||
energy += gx * gx + gy * gy;
|
||||
samples++;
|
||||
}
|
||||
}
|
||||
return samples == 0 ? 0 : energy / samples - NoiseGradientGain * sigma * sigma;
|
||||
}
|
||||
|
||||
private FrameMotion FitSimilarity(ReadOnlySpan<Match> matches)
|
||||
{
|
||||
var n = matches.Length;
|
||||
if (n == 0) return new FrameMotion(Affine2D.Identity, 0, 0);
|
||||
|
||||
Span<bool> inliers = stackalloc bool[n];
|
||||
Span<bool> best = stackalloc bool[n];
|
||||
var bestCount = 0;
|
||||
var bestResidual = double.PositiveInfinity;
|
||||
Span<bool> pair = stackalloc bool[n];
|
||||
for (var a = 0; a < n; a++)
|
||||
{
|
||||
for (var b = a + 1; b < n; b++)
|
||||
{
|
||||
pair.Clear();
|
||||
pair[a] = pair[b] = true;
|
||||
var model = Similarity(matches, pair);
|
||||
if (double.Abs(model.Angle) > Options.MaxRotation || double.Abs(double.Log(model.Scale)) > Options.MaxScaleChange) continue;
|
||||
Consider(model, matches, inliers, best, ref bestCount, ref bestResidual);
|
||||
}
|
||||
}
|
||||
|
||||
// Translation hypotheses, one per vector: covers a single valid patch and sets of implausible pairs.
|
||||
if (bestCount < 2)
|
||||
{
|
||||
foreach (var m in matches) Consider(Affine2D.Translation(m.Qx - m.Px, m.Qy - m.Py), matches, inliers, best, ref bestCount, ref bestResidual);
|
||||
return new FrameMotion(Translation(matches, best), n, bestCount);
|
||||
}
|
||||
return new FrameMotion(Similarity(matches, best), n, bestCount);
|
||||
}
|
||||
|
||||
/// <summary>Scores a hypothesis and keeps it when it has more inliers (ties: smaller summed residual).</summary>
|
||||
private void Consider(Affine2D model, ReadOnlySpan<Match> matches, Span<bool> inliers, Span<bool> best, ref int bestCount, ref double bestResidual)
|
||||
{
|
||||
var count = 0;
|
||||
double residual = 0;
|
||||
for (var i = 0; i < matches.Length; i++)
|
||||
{
|
||||
var m = matches[i];
|
||||
var (x, y) = model.Apply(m.Px, m.Py);
|
||||
var r = double.Hypot(x - m.Qx, y - m.Qy);
|
||||
inliers[i] = r <= Options.InlierThreshold;
|
||||
if (!inliers[i]) continue;
|
||||
count++;
|
||||
residual += r;
|
||||
}
|
||||
if (count < bestCount || (count == bestCount && residual >= bestResidual)) return;
|
||||
bestCount = count;
|
||||
bestResidual = residual;
|
||||
inliers.CopyTo(best);
|
||||
}
|
||||
|
||||
/// <summary>Weighted least-squares similarity q ≈ [a −b; b a]·p + t over the selected correspondences.</summary>
|
||||
private static Affine2D Similarity(ReadOnlySpan<Match> matches, ReadOnlySpan<bool> selected)
|
||||
{
|
||||
double sw = 0, mpx = 0, mpy = 0, mqx = 0, mqy = 0;
|
||||
for (var i = 0; i < matches.Length; i++)
|
||||
{
|
||||
if (!selected[i]) continue;
|
||||
var m = matches[i];
|
||||
sw += m.Weight;
|
||||
mpx += m.Weight * m.Px;
|
||||
mpy += m.Weight * m.Py;
|
||||
mqx += m.Weight * m.Qx;
|
||||
mqy += m.Weight * m.Qy;
|
||||
}
|
||||
mpx /= sw;
|
||||
mpy /= sw;
|
||||
mqx /= sw;
|
||||
mqy /= sw;
|
||||
double dot = 0, cross = 0, norm = 0;
|
||||
for (var i = 0; i < matches.Length; i++)
|
||||
{
|
||||
if (!selected[i]) continue;
|
||||
var m = matches[i];
|
||||
double ax = m.Px - mpx, ay = m.Py - mpy, bx = m.Qx - mqx, by = m.Qy - mqy;
|
||||
dot += m.Weight * (ax * bx + ay * by);
|
||||
cross += m.Weight * (ax * by - ay * bx);
|
||||
norm += m.Weight * (ax * ax + ay * ay);
|
||||
}
|
||||
if (norm <= 1e-12) return Affine2D.Translation(mqx - mpx, mqy - mpy);
|
||||
var a = dot / norm;
|
||||
var b = cross / norm;
|
||||
return new Affine2D(a, -b, b, a, mqx - (a * mpx - b * mpy), mqy - (b * mpx + a * mpy));
|
||||
}
|
||||
|
||||
private static Affine2D Translation(ReadOnlySpan<Match> matches, ReadOnlySpan<bool> selected)
|
||||
{
|
||||
double sw = 0, tx = 0, ty = 0;
|
||||
for (var i = 0; i < matches.Length; i++)
|
||||
{
|
||||
if (!selected[i]) continue;
|
||||
var m = matches[i];
|
||||
sw += m.Weight;
|
||||
tx += m.Weight * (m.Qx - m.Px);
|
||||
ty += m.Weight * (m.Qy - m.Py);
|
||||
}
|
||||
return sw > 0 ? Affine2D.Translation(tx / sw, ty / sw) : Affine2D.Identity;
|
||||
}
|
||||
|
||||
/// <summary>RMS displacement of the patch-grid centres under the corrections.</summary>
|
||||
private double ShakeRms(Affine2D[] corrections)
|
||||
{
|
||||
double sum = 0;
|
||||
var half = (PatchSize - 1) / 2.0;
|
||||
foreach (var k in corrections)
|
||||
{
|
||||
foreach (var (x0, y0) in _patches)
|
||||
{
|
||||
var (x, y) = k.Apply(x0 + half, y0 + half);
|
||||
sum += (x - x0 - half) * (x - x0 - half) + (y - y0 - half) * (y - y0 - half);
|
||||
}
|
||||
}
|
||||
return double.Sqrt(sum / (corrections.Length * _patches.Length));
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Largest scale f of a centred, frame-shaped output rectangle whose corners map inside the source under
|
||||
/// every inverse correction (each corner gives linear bounds on f).
|
||||
/// </summary>
|
||||
private double CropScale(Affine2D[] corrections)
|
||||
{
|
||||
double cx = (Width - 1) / 2.0, cy = (Height - 1) / 2.0;
|
||||
double hx = Width / 2.0, hy = Height / 2.0;
|
||||
double minX = -0.5, minY = -0.5, maxX = Width - 0.5, maxY = Height - 0.5;
|
||||
var scale = 1.0;
|
||||
foreach (var correction in corrections)
|
||||
{
|
||||
var inverse = correction.Invert();
|
||||
var (ox, oy) = inverse.Apply(cx, cy);
|
||||
if (ox < minX || ox > maxX || oy < minY || oy > maxY) return 0;
|
||||
for (var corner = 0; corner < 4; corner++)
|
||||
{
|
||||
var (dx, dy) = inverse.ApplyVector((corner & 1) == 0 ? -hx : hx, (corner & 2) == 0 ? -hy : hy);
|
||||
scale = Limit(scale, ox, dx, minX, maxX);
|
||||
scale = Limit(scale, oy, dy, minY, maxY);
|
||||
}
|
||||
}
|
||||
return double.Clamp(scale, 0, 1);
|
||||
|
||||
static double Limit(double f, double origin, double direction, double min, double max)
|
||||
{
|
||||
if (direction > 0) return double.Min(f, (max - origin) / direction);
|
||||
if (direction < 0) return double.Min(f, (min - origin) / direction);
|
||||
return f;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>Patch centre in the previous frame (P) and where its content moved in the current one (Q).</summary>
|
||||
private readonly record struct Match(double Px, double Py, double Qx, double Qy, double Weight);
|
||||
}
|
||||
@@ -0,0 +1,253 @@
|
||||
using System.Numerics;
|
||||
using Titano.Core.Imaging;
|
||||
|
||||
namespace Titano.Core.Motion;
|
||||
|
||||
/// <summary>How a <see cref="TemporalStacker"/> combines its window.</summary>
|
||||
public enum StackMode
|
||||
{
|
||||
/// <summary>Per-pixel median: removes transients (aircraft, birds, people) present in under half the frames.</summary>
|
||||
Median,
|
||||
|
||||
/// <summary>Per-pixel mean: noise reduction by √N for static scenes.</summary>
|
||||
Mean,
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Sliding-window temporal stacking. <see cref="Push"/> copies frames into a ring of pooled buffers;
|
||||
/// <see cref="Render"/> combines the frames currently in the window. Medians are exact: for up to
|
||||
/// <see cref="NetworkLimit"/> frames an odd–even transposition sorting network runs on Vector<float>
|
||||
/// lanes (many pixels per instruction, no branches), beyond that Hoare's selection runs per pixel.
|
||||
/// Rows of every channel run in parallel.
|
||||
/// </summary>
|
||||
public sealed class TemporalStacker : IDisposable
|
||||
{
|
||||
/// <summary>Largest frame count sorted by the vectorised network (N² min/max per lane block).</summary>
|
||||
public const int NetworkLimit = 32;
|
||||
|
||||
private readonly ImageBuffer?[] _ring;
|
||||
private int _next;
|
||||
|
||||
public TemporalStacker(int window, StackMode mode)
|
||||
{
|
||||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(window);
|
||||
Window = window;
|
||||
Mode = mode;
|
||||
_ring = new ImageBuffer?[window];
|
||||
}
|
||||
|
||||
public int Window { get; }
|
||||
|
||||
public StackMode Mode { get; }
|
||||
|
||||
/// <summary>Frames currently in the window.</summary>
|
||||
public int Count { get; private set; }
|
||||
|
||||
public bool IsFull => Count == Window;
|
||||
|
||||
/// <summary>Adds a copy of <paramref name="frame"/>, evicting the oldest frame once the window is full.</summary>
|
||||
public void Push(ImageBuffer frame)
|
||||
{
|
||||
var first = _ring[0];
|
||||
if (first is not null && (first.Width != frame.Width || first.Height != frame.Height || first.Channels != frame.Channels))
|
||||
throw new ArgumentException("Frame differs in size or channels from the window.", nameof(frame));
|
||||
var slot = _ring[_next] ??= new ImageBuffer(frame.Width, frame.Height, frame.Channels, clear: false);
|
||||
frame.CopyTo(slot);
|
||||
_next = (_next + 1) % Window;
|
||||
Count = int.Min(Count + 1, Window);
|
||||
}
|
||||
|
||||
/// <summary>Combines the frames in the window into <paramref name="destination"/>.</summary>
|
||||
public void Render(ImageBuffer destination, CancellationToken cancellationToken = default)
|
||||
{
|
||||
if (Count == 0) throw new InvalidOperationException("The window is empty.");
|
||||
var frames = new ImageBuffer[Count];
|
||||
for (var i = 0; i < Count; i++) frames[i] = _ring[i]!;
|
||||
if (Mode == StackMode.Median) Median(frames, destination, cancellationToken);
|
||||
else Mean(frames, destination, cancellationToken);
|
||||
}
|
||||
|
||||
/// <summary>Empties the window (buffers are kept for reuse).</summary>
|
||||
public void Clear()
|
||||
{
|
||||
Count = 0;
|
||||
_next = 0;
|
||||
}
|
||||
|
||||
public void Dispose()
|
||||
{
|
||||
for (var i = 0; i < _ring.Length; i++)
|
||||
{
|
||||
_ring[i]?.Dispose();
|
||||
_ring[i] = null;
|
||||
}
|
||||
Clear();
|
||||
}
|
||||
|
||||
/// <summary>Exact per-pixel, per-channel median (mean of the middle pair for even counts).</summary>
|
||||
public static void Median(IReadOnlyList<ImageBuffer> frames, ImageBuffer destination, CancellationToken cancellationToken = default)
|
||||
{
|
||||
var planes = Validate(frames, destination);
|
||||
var n = frames.Count;
|
||||
var dst = destination.Storage;
|
||||
ForRows(destination, cancellationToken, (offset, length) =>
|
||||
{
|
||||
var i = 0;
|
||||
if (n <= NetworkLimit && Vector.IsHardwareAccelerated)
|
||||
{
|
||||
Span<Vector<float>> lanes = stackalloc Vector<float>[n];
|
||||
var vc = Vector<float>.Count;
|
||||
for (; i <= length - vc; i += vc)
|
||||
{
|
||||
var at = offset + i;
|
||||
for (var k = 0; k < n; k++) lanes[k] = new Vector<float>(planes[k], at);
|
||||
var median = PlaneOps.MedianOfLanes(lanes);
|
||||
median.CopyTo(dst, at);
|
||||
}
|
||||
}
|
||||
Span<float> values = n <= 256 ? stackalloc float[n] : new float[n];
|
||||
for (; i < length; i++)
|
||||
{
|
||||
var at = offset + i;
|
||||
for (var k = 0; k < n; k++) values[k] = planes[k][at];
|
||||
dst[at] = PlaneOps.Median(values);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
/// <summary>Per-pixel, per-channel arithmetic mean.</summary>
|
||||
public static void Mean(IReadOnlyList<ImageBuffer> frames, ImageBuffer destination, CancellationToken cancellationToken = default)
|
||||
{
|
||||
var planes = Validate(frames, destination);
|
||||
var dst = destination.Storage;
|
||||
var scale = 1f / frames.Count;
|
||||
ForRows(destination, cancellationToken, (offset, length) =>
|
||||
{
|
||||
var span = dst.AsSpan(offset, length);
|
||||
planes[0].AsSpan(offset, length).CopyTo(span);
|
||||
for (var k = 1; k < planes.Length; k++) Accumulate(span, planes[k].AsSpan(offset, length));
|
||||
Scale(span, scale);
|
||||
});
|
||||
}
|
||||
|
||||
private static float[][] Validate(IReadOnlyList<ImageBuffer> frames, ImageBuffer destination)
|
||||
{
|
||||
if (frames.Count == 0) throw new ArgumentException("At least one frame is required.", nameof(frames));
|
||||
var planes = new float[frames.Count][];
|
||||
for (var i = 0; i < frames.Count; i++)
|
||||
{
|
||||
var f = frames[i];
|
||||
if (f.Width != destination.Width || f.Height != destination.Height || f.Channels != destination.Channels)
|
||||
throw new ArgumentException("Frames and destination must share size and channels.", nameof(frames));
|
||||
planes[i] = f.Storage;
|
||||
}
|
||||
return planes;
|
||||
}
|
||||
|
||||
/// <summary>Runs <paramref name="body"/>(offset, length) over every row of every channel, in parallel when large.</summary>
|
||||
private static void ForRows(ImageBuffer destination, CancellationToken cancellationToken, Action<int, int> body)
|
||||
{
|
||||
var rows = destination.Height * destination.Channels;
|
||||
var width = destination.Width;
|
||||
if ((long)rows * width < PlaneOps.ParallelThreshold)
|
||||
{
|
||||
for (var r = 0; r < rows; r++)
|
||||
{
|
||||
cancellationToken.ThrowIfCancellationRequested();
|
||||
body(r * width, width);
|
||||
}
|
||||
}
|
||||
else
|
||||
{
|
||||
Parallel.For(0, rows, new ParallelOptions { CancellationToken = cancellationToken }, r => body(r * width, width));
|
||||
}
|
||||
}
|
||||
|
||||
private static void Accumulate(Span<float> sum, ReadOnlySpan<float> values)
|
||||
{
|
||||
var i = 0;
|
||||
if (Vector.IsHardwareAccelerated)
|
||||
{
|
||||
for (; i <= sum.Length - Vector<float>.Count; i += Vector<float>.Count)
|
||||
(new Vector<float>(sum[i..]) + new Vector<float>(values[i..])).CopyTo(sum[i..]);
|
||||
}
|
||||
for (; i < sum.Length; i++) sum[i] += values[i];
|
||||
}
|
||||
|
||||
private static void Scale(Span<float> values, float factor)
|
||||
{
|
||||
var i = 0;
|
||||
if (Vector.IsHardwareAccelerated)
|
||||
{
|
||||
for (; i <= values.Length - Vector<float>.Count; i += Vector<float>.Count)
|
||||
(new Vector<float>(values[i..]) * factor).CopyTo(values[i..]);
|
||||
}
|
||||
for (; i < values.Length; i++) values[i] *= factor;
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Star trails by progressive maximum with exponential decay: acc ← max(acc · decay, frame) per pixel and
|
||||
/// channel. Decay 1 keeps every trail forever (the accumulator never decreases); smaller values make
|
||||
/// trails fade behind the stars (see <see cref="DecayForTrailLength"/>).
|
||||
/// </summary>
|
||||
public sealed class StarTrailStacker : IDisposable
|
||||
{
|
||||
/// <summary>Relative brightness a trail point has fallen to after its trail length.</summary>
|
||||
public const double TrailFloor = 0.01;
|
||||
|
||||
private ImageBuffer? _accumulator;
|
||||
|
||||
public StarTrailStacker(double decay = 1.0)
|
||||
{
|
||||
if (!(decay is > 0 and <= 1)) throw new ArgumentOutOfRangeException(nameof(decay), "Decay must lie in (0, 1].");
|
||||
Decay = decay;
|
||||
}
|
||||
|
||||
public double Decay { get; }
|
||||
|
||||
/// <summary>Frames added so far.</summary>
|
||||
public int Count { get; private set; }
|
||||
|
||||
/// <summary>The running result (null before the first frame); owned by the stacker.</summary>
|
||||
public ImageBuffer? Result => _accumulator;
|
||||
|
||||
/// <summary>
|
||||
/// Decay that fades a trail point to <see cref="TrailFloor"/> (1 %) of its brightness after
|
||||
/// <paramref name="frames"/> frames: 0.01^(1/frames). Infinite or non-positive lengths give 1 (endless trails).
|
||||
/// </summary>
|
||||
public static double DecayForTrailLength(double frames) =>
|
||||
frames > 0 && double.IsFinite(frames) ? double.Pow(TrailFloor, 1 / frames) : 1.0;
|
||||
|
||||
/// <summary>Folds the next frame into the trails.</summary>
|
||||
public void Add(ImageBuffer frame)
|
||||
{
|
||||
if (_accumulator is null)
|
||||
{
|
||||
_accumulator = frame.Clone();
|
||||
Count = 1;
|
||||
return;
|
||||
}
|
||||
if (frame.Width != _accumulator.Width || frame.Height != _accumulator.Height || frame.Channels != _accumulator.Channels)
|
||||
throw new ArgumentException("Frame differs in size or channels.", nameof(frame));
|
||||
|
||||
var acc = _accumulator.Data;
|
||||
var src = frame.Data;
|
||||
var decay = (float)Decay;
|
||||
var i = 0;
|
||||
if (Vector.IsHardwareAccelerated)
|
||||
{
|
||||
for (; i <= acc.Length - Vector<float>.Count; i += Vector<float>.Count)
|
||||
Vector.Max(new Vector<float>(acc[i..]) * decay, new Vector<float>(src[i..])).CopyTo(acc[i..]);
|
||||
}
|
||||
for (; i < acc.Length; i++) acc[i] = float.Max(acc[i] * decay, src[i]);
|
||||
Count++;
|
||||
}
|
||||
|
||||
public void Dispose()
|
||||
{
|
||||
_accumulator?.Dispose();
|
||||
_accumulator = null;
|
||||
Count = 0;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,87 @@
|
||||
using Titano.Core.Imaging.Geometry;
|
||||
|
||||
namespace Titano.Core.Motion;
|
||||
|
||||
/// <summary>
|
||||
/// Virtual camera pose: view centre in normalised source coordinates (0..1 across the frame), zoom ≥ 1
|
||||
/// (1 shows the whole frame) and roll in degrees (positive turns the camera clockwise on screen, so the
|
||||
/// content appears turned counter-clockwise).
|
||||
/// </summary>
|
||||
public readonly record struct CameraState(double CenterX, double CenterY, double Zoom, double Rotation);
|
||||
|
||||
/// <summary>A virtual camera keyframe; <see cref="Easing"/> shapes the segment from this keyframe to the next.</summary>
|
||||
public readonly record struct CameraKeyframe(double Frame, double CenterX, double CenterY, double Zoom, double Rotation)
|
||||
{
|
||||
public BezierEasing Easing { get; init; } = BezierEasing.EaseInOut;
|
||||
|
||||
public CameraState State => new(CenterX, CenterY, Zoom, Rotation);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Ken Burns style pan/zoom/roll: keyframes interpolated with per-segment cubic Bézier easing (centre and
|
||||
/// roll linearly in the eased progress, zoom geometrically so equal steps look equally fast). The pose
|
||||
/// becomes one affine that is composed with the stabiliser correction, so the frame is resampled once.
|
||||
/// </summary>
|
||||
public sealed class VirtualCamera
|
||||
{
|
||||
private readonly CameraKeyframe[] _keyframes;
|
||||
|
||||
public VirtualCamera(IEnumerable<CameraKeyframe> keyframes)
|
||||
{
|
||||
_keyframes = keyframes.OrderBy(k => k.Frame).ToArray();
|
||||
if (_keyframes.Length == 0) throw new ArgumentException("At least one keyframe is required.", nameof(keyframes));
|
||||
for (var i = 0; i < _keyframes.Length; i++)
|
||||
{
|
||||
var k = _keyframes[i];
|
||||
if (!(k.Zoom >= 1) || !double.IsFinite(k.Zoom)) throw new ArgumentOutOfRangeException(nameof(keyframes), "Zoom must be ≥ 1.");
|
||||
if (!double.IsFinite(k.Frame + k.CenterX + k.CenterY + k.Rotation)) throw new ArgumentOutOfRangeException(nameof(keyframes), "Keyframe values must be finite.");
|
||||
if (i > 0 && k.Frame == _keyframes[i - 1].Frame) throw new ArgumentException("Two keyframes share a frame.", nameof(keyframes));
|
||||
}
|
||||
}
|
||||
|
||||
public IReadOnlyList<CameraKeyframe> Keyframes => _keyframes;
|
||||
|
||||
/// <summary>Pose at a (possibly fractional) output frame; held constant before the first and after the last keyframe.</summary>
|
||||
public CameraState Evaluate(double frame)
|
||||
{
|
||||
if (frame <= _keyframes[0].Frame) return _keyframes[0].State;
|
||||
if (frame >= _keyframes[^1].Frame) return _keyframes[^1].State;
|
||||
var i = 0;
|
||||
while (_keyframes[i + 1].Frame <= frame) i++;
|
||||
var a = _keyframes[i];
|
||||
if (frame == a.Frame) return a.State;
|
||||
var b = _keyframes[i + 1];
|
||||
var p = a.Easing.Evaluate((frame - a.Frame) / (b.Frame - a.Frame));
|
||||
return new CameraState(
|
||||
a.CenterX + (b.CenterX - a.CenterX) * p,
|
||||
a.CenterY + (b.CenterY - a.CenterY) * p,
|
||||
a.Zoom * double.Pow(b.Zoom / a.Zoom, p),
|
||||
a.Rotation + (b.Rotation - a.Rotation) * p);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Maps view pixel-centre coordinates (a frame-sized view) to source pixel-centre coordinates:
|
||||
/// x_src = C + R(roll)·(x_view − view centre) / zoom.
|
||||
/// </summary>
|
||||
public static Affine2D ViewToSource(CameraState state, int sourceWidth, int sourceHeight)
|
||||
{
|
||||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(sourceWidth);
|
||||
ArgumentOutOfRangeException.ThrowIfNegativeOrZero(sourceHeight);
|
||||
var centreX = state.CenterX * sourceWidth - 0.5;
|
||||
var centreY = state.CenterY * sourceHeight - 0.5;
|
||||
return Affine2D.Translation(centreX, centreY)
|
||||
* Affine2D.Similarity(1 / state.Zoom, state.Rotation * double.Pi / 180, 0, 0)
|
||||
* Affine2D.Translation(-(sourceWidth - 1) / 2.0, -(sourceHeight - 1) / 2.0);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// The single view→source map for an output frame: the camera view composed with the inverse of the
|
||||
/// stabiliser correction (which maps source to stabilised coordinates). Feed it to
|
||||
/// <see cref="GeometrySettings.Warp"/>.
|
||||
/// </summary>
|
||||
public Affine2D ToSource(double frame, int sourceWidth, int sourceHeight, Affine2D? stabilization = null)
|
||||
{
|
||||
var view = ViewToSource(Evaluate(frame), sourceWidth, sourceHeight);
|
||||
return stabilization is { } correction ? correction.Invert() * view : view;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,56 @@
|
||||
using Titano.Core.Imaging.Geometry;
|
||||
using Titano.Testing;
|
||||
|
||||
namespace Titano.Core.Tests.Geometry;
|
||||
|
||||
public sealed class Affine2DTests
|
||||
{
|
||||
[Test]
|
||||
public void CompositionAppliesInnerFirst()
|
||||
{
|
||||
var scale = Affine2D.Scaling(2, 3);
|
||||
var move = Affine2D.Translation(5, -1);
|
||||
var (x, y) = (move * scale).Apply(1, 1);
|
||||
Assert.Approximately(7, x, 1e-15);
|
||||
Assert.Approximately(2, y, 1e-15);
|
||||
Assert.Equal(move * scale, scale.Then(move));
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void InverseUndoesTheMap()
|
||||
{
|
||||
var map = Affine2D.Similarity(1.3, 0.4, 12, -7) * Affine2D.Scaling(1, 0.8);
|
||||
var inverse = map.Invert();
|
||||
Assert.True((inverse * map).IsIdentity(1e-12));
|
||||
Assert.True((map * inverse).IsIdentity(1e-12));
|
||||
var (x, y) = map.Apply(3.5, -2.25);
|
||||
var (bx, by) = inverse.Apply(x, y);
|
||||
Assert.Within(3.5, -2.25, bx, by, 1e-12);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void SingularMapsDoNotInvert()
|
||||
{
|
||||
Assert.False(new Affine2D(1, 2, 2, 4, 0, 0).TryInvert(out _));
|
||||
Assert.Throws<InvalidOperationException>(() => Affine2D.Scaling(0, 1).Invert());
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void RotationAboutPivotKeepsThePivot()
|
||||
{
|
||||
var map = Affine2D.About(Affine2D.Rotation(0.7), 40, 30);
|
||||
var (x, y) = map.Apply(40, 30);
|
||||
Assert.Within(40, 30, x, y, 1e-12);
|
||||
var (vx, vy) = map.ApplyVector(1, 0);
|
||||
Assert.Within(double.Cos(0.7), double.Sin(0.7), vx, vy, 1e-15);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void SimilarityDecomposes()
|
||||
{
|
||||
var map = Affine2D.Similarity(1.25, -0.3, 4, 5);
|
||||
Assert.Approximately(1.25, map.Scale, 1e-12);
|
||||
Assert.Approximately(-0.3, map.Angle, 1e-12);
|
||||
Assert.Approximately(1.25 * 1.25, map.Determinant, 1e-12);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,54 @@
|
||||
using Titano.Core.Imaging.Geometry;
|
||||
using Titano.Testing;
|
||||
|
||||
namespace Titano.Core.Tests.Geometry;
|
||||
|
||||
public sealed class AspectRatioTests
|
||||
{
|
||||
[Theory]
|
||||
[Case(1920.0, 1080.0, 1, 1, 420.0, 0.0, 1080.0, 1080.0)]
|
||||
[Case(1920.0, 1080.0, 9, 16, 656.25, 0.0, 607.5, 1080.0)]
|
||||
[Case(4000.0, 3000.0, 16, 9, 0.0, 375.0, 4000.0, 2250.0)]
|
||||
[Case(6000.0, 4000.0, 3, 2, 0.0, 0.0, 6000.0, 4000.0)]
|
||||
[Case(1080.0, 1920.0, 4, 5, 0.0, 285.0, 1080.0, 1350.0)]
|
||||
[Case(3840.0, 2160.0, 21, 9, 0.0, 257.142857142857, 3840.0, 1645.71428571429)]
|
||||
public void FitCropCentresTheLargestCrop(double bw, double bh, int w, int h, double x, double y, double cw, double ch)
|
||||
{
|
||||
var crop = AspectRatio.FitCrop(RectD.FromSize(bw, bh), AspectRatio.Custom(w, h).Resolve(bw, bh));
|
||||
Assert.Approximately(x, crop.X, 1e-9);
|
||||
Assert.Approximately(y, crop.Y, 1e-9);
|
||||
Assert.Approximately(cw, crop.Width, 1e-9);
|
||||
Assert.Approximately(ch, crop.Height, 1e-9);
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[Case(-1.0, 100.0)]
|
||||
[Case(0.0, 280.0)]
|
||||
[Case(1.0, 460.0)]
|
||||
[Case(5.0, 460.0)]
|
||||
[Case(-0.5, 190.0)]
|
||||
public void FitCropOffsetMovesWithinTheSlack(double offset, double expectedX)
|
||||
{
|
||||
var crop = AspectRatio.FitCrop(new RectD(100, 50, 720, 360), 1.0, offset, offset);
|
||||
Assert.Approximately(expectedX, crop.X, 1e-9);
|
||||
Assert.Approximately(50, crop.Y, 1e-9);
|
||||
Assert.Approximately(360, crop.Width, 1e-9);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void PresetsAndParsing()
|
||||
{
|
||||
Assert.Equal(AspectRatio.Widescreen, AspectRatio.Custom(32, 18));
|
||||
Assert.Equal("16:9", AspectRatio.Widescreen.ToString());
|
||||
Assert.Equal("9:16", AspectRatio.Vertical.ToString());
|
||||
Assert.Equal(8, AspectRatio.Presets.Count);
|
||||
Assert.Approximately(1.5, AspectRatio.Source.Resolve(6000, 4000), 1e-15);
|
||||
Assert.Approximately(21.0 / 9, AspectRatio.Cinema.Resolve(6000, 4000), 1e-15);
|
||||
Assert.True(AspectRatio.TryParse("4/5", out var portrait));
|
||||
Assert.Equal(AspectRatio.Portrait, portrait);
|
||||
Assert.True(AspectRatio.TryParse("source", out var source));
|
||||
Assert.True(source.IsSource);
|
||||
Assert.False(AspectRatio.TryParse("16:0", out _));
|
||||
Assert.False(AspectRatio.TryParse("wide", out _));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,133 @@
|
||||
using Titano.Core.Imaging;
|
||||
using Titano.Core.Imaging.Geometry;
|
||||
using Titano.Core.Tests.Motion;
|
||||
using Titano.Testing;
|
||||
|
||||
namespace Titano.Core.Tests.Geometry;
|
||||
|
||||
public sealed class GeometryStageTests
|
||||
{
|
||||
private const int Size = 128;
|
||||
|
||||
private readonly TestContext _context;
|
||||
|
||||
public GeometryStageTests(TestContext context) => _context = context;
|
||||
|
||||
[Test]
|
||||
public void IdentityWarpReproducesTheImage()
|
||||
{
|
||||
using var source = Texture(sigma: 1.0);
|
||||
using var output = GeometryStage.Apply(source, new GeometrySettings());
|
||||
Assert.Equal(Size, output.Width);
|
||||
Assert.Equal(3, output.Channels);
|
||||
var psnr = SyntheticImages.Psnr(source.Plane(1), output.Plane(1), Size, 0, 0, Size, Size);
|
||||
_context.Log($"identity PSNR {psnr:F1} dB");
|
||||
Assert.GreaterOrEqual(psnr, 60);
|
||||
Assert.True(source.Data.SequenceEqual(output.Data));
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void HalfPixelShiftAndBackStaysWithinBounds()
|
||||
{
|
||||
using var source = Texture(sigma: 2.0);
|
||||
using var shifted = new ImageBuffer(Size, Size);
|
||||
using var back = new ImageBuffer(Size, Size);
|
||||
GeometryStage.Warp(source, shifted, Affine2D.Translation(0.5, 0.5));
|
||||
GeometryStage.Warp(shifted, back, Affine2D.Translation(-0.5, -0.5));
|
||||
var psnr = SyntheticImages.Psnr(source.Plane(0), back.Plane(0), Size, 4, 4, Size - 4, Size - 4);
|
||||
_context.Log($"0.5 px round trip PSNR {psnr:F1} dB");
|
||||
Assert.GreaterOrEqual(psnr, 40);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void LinearRampsAreReproducedUnderSubPixelWarps()
|
||||
{
|
||||
using var ramp = new ImageBuffer(64, 64, 1);
|
||||
for (var y = 0; y < 64; y++)
|
||||
for (var x = 0; x < 64; x++)
|
||||
ramp[0, x, y] = 0.01f * x + 0.005f * y;
|
||||
using var output = new ImageBuffer(64, 64, 1);
|
||||
var map = Affine2D.About(Affine2D.Similarity(0.8, 0.2, 0, 0), 32, 32);
|
||||
GeometryStage.Warp(ramp, output, map);
|
||||
for (var y = 8; y < 56; y++)
|
||||
{
|
||||
for (var x = 8; x < 56; x++)
|
||||
{
|
||||
var (sx, sy) = map.Apply(x, y);
|
||||
Assert.Approximately(0.01 * sx + 0.005 * sy, output[0, x, y], 2e-6);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void TransparentBordersCarryCoverage()
|
||||
{
|
||||
using var source = Texture(sigma: 1.0);
|
||||
using var output = GeometryStage.Apply(source, new GeometrySettings
|
||||
{
|
||||
Warp = Affine2D.Translation(-10, 0),
|
||||
Border = BorderMode.Transparent,
|
||||
});
|
||||
Assert.Equal(4, output.Channels);
|
||||
for (var y = 0; y < Size; y += 7)
|
||||
{
|
||||
Assert.Equal(0f, output[3, 3, y]);
|
||||
Assert.Equal(0f, output[0, 3, y]);
|
||||
Assert.Equal(1f, output[3, 40, y]);
|
||||
Assert.Equal(source[1, 30, y], output[1, 40, y]);
|
||||
}
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void ClampReplicatesEdges()
|
||||
{
|
||||
using var source = Texture(sigma: 1.0);
|
||||
using var output = GeometryStage.Apply(source, new GeometrySettings { Warp = Affine2D.Translation(-10, 0) });
|
||||
for (var y = 0; y < Size; y += 5) Assert.Approximately(source[2, 0, y], output[2, 2, y], 1e-6);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void PlanFitsAspectAndMapsPixelCentres()
|
||||
{
|
||||
var plan = GeometryStage.Plan(1920, 1080, new GeometrySettings { Aspect = AspectRatio.Square, OutputWidth = 540 });
|
||||
Assert.Equal(540, plan.OutputWidth);
|
||||
Assert.Equal(540, plan.OutputHeight);
|
||||
Assert.Equal(new RectD(420, 0, 1080, 1080), plan.Crop);
|
||||
var (x, y) = plan.OutputToSource.Apply(0, 0);
|
||||
Assert.Within(420.5, 0.5, x, y, 1e-12);
|
||||
|
||||
var cropped = GeometryStage.Plan(800, 600, new GeometrySettings { Crop = new RectD(100, 50, 200, 100), OutputWidth = 400, OutputHeight = 200 });
|
||||
Assert.Equal(new RectD(100, 50, 200, 100), cropped.Crop);
|
||||
var (cx, cy) = cropped.OutputToSource.Apply(0, 0);
|
||||
Assert.Within(99.75, 49.75, cx, cy, 1e-12);
|
||||
|
||||
var vertical = GeometryStage.Plan(1920, 1080, new GeometrySettings { Aspect = AspectRatio.Vertical, OutputHeight = 1920 });
|
||||
Assert.Equal(1080, vertical.OutputWidth);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void DownscalingDoesNotAlias()
|
||||
{
|
||||
using var checker = new ImageBuffer(256, 256, 1);
|
||||
for (var y = 0; y < 256; y++)
|
||||
for (var x = 0; x < 256; x++)
|
||||
checker[0, x, y] = (x + y) % 2 == 0 ? 1f : 0f;
|
||||
using var small = GeometryStage.Apply(checker, new GeometrySettings { OutputWidth = 64 });
|
||||
Assert.Equal(64, small.Height);
|
||||
for (var y = 2; y < 62; y++)
|
||||
for (var x = 2; x < 62; x++)
|
||||
Assert.Approximately(0.5, small[0, x, y], 0.02);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void CancellationStopsTheWarp()
|
||||
{
|
||||
using var source = Texture(sigma: 1.0);
|
||||
using var cts = new CancellationTokenSource();
|
||||
cts.Cancel();
|
||||
Assert.Throws<OperationCanceledException>(() => GeometryStage.Apply(source, new GeometrySettings(), cts.Token));
|
||||
}
|
||||
|
||||
private static ImageBuffer Texture(double sigma) =>
|
||||
SyntheticImages.ToRgb(SyntheticImages.Crop(SyntheticImages.Noise(Size, sigma, seed: 21), Size, 0, 0, Size, Size), Size, Size);
|
||||
}
|
||||
@@ -0,0 +1,183 @@
|
||||
using Titano.Core.Motion;
|
||||
using Titano.Testing;
|
||||
|
||||
namespace Titano.Core.Tests.Motion;
|
||||
|
||||
public sealed class FourierTests
|
||||
{
|
||||
private readonly TestContext _context;
|
||||
|
||||
public FourierTests(TestContext context) => _context = context;
|
||||
|
||||
[Theory]
|
||||
[Case(1)]
|
||||
[Case(2)]
|
||||
[Case(64)]
|
||||
[Case(1024)]
|
||||
[Case(4096)]
|
||||
public void PowerOfTwoRoundTrip(int n)
|
||||
{
|
||||
var (re, im) = RandomSignal(n, seed: n);
|
||||
var (r0, i0) = ((double[])re.Clone(), (double[])im.Clone());
|
||||
Fourier.Forward(re, im);
|
||||
Fourier.Inverse(re, im);
|
||||
var error = MaxError(r0, i0, re, im);
|
||||
_context.Log($"n = {n}: round-trip max error {error:E2}");
|
||||
Assert.LessOrEqual(error, 1e-5);
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[Case(3)]
|
||||
[Case(7)]
|
||||
[Case(13)]
|
||||
[Case(97)]
|
||||
[Case(251)]
|
||||
[Case(1009)]
|
||||
public void BluesteinMatchesDirectDftForPrimes(int n)
|
||||
{
|
||||
var (re, im) = RandomSignal(n, seed: n);
|
||||
var (er, ei) = Dft(re, im);
|
||||
Fourier.Forward(re, im);
|
||||
var error = MaxError(er, ei, re, im) / double.Sqrt(n);
|
||||
_context.Log($"n = {n}: Bluestein vs direct DFT, max error / √n {error:E2}");
|
||||
Assert.LessOrEqual(error, 1e-9);
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[Case(12)]
|
||||
[Case(100)]
|
||||
[Case(1000)]
|
||||
public void CompositeLengthsRoundTrip(int n)
|
||||
{
|
||||
var (re, im) = RandomSignal(n, seed: 3 * n);
|
||||
var (r0, i0) = ((double[])re.Clone(), (double[])im.Clone());
|
||||
Fourier.Forward(re, im);
|
||||
Fourier.Inverse(re, im);
|
||||
Assert.LessOrEqual(MaxError(r0, i0, re, im), 1e-5);
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[Case(64)]
|
||||
[Case(100)]
|
||||
[Case(15)]
|
||||
public void RealTransformMatchesComplexAndRoundTrips(int n)
|
||||
{
|
||||
var (signal, _) = RandomSignal(n, seed: 11 * n);
|
||||
var bins = n / 2 + 1;
|
||||
var hr = new double[bins];
|
||||
var hi = new double[bins];
|
||||
Fourier.ForwardReal(signal, hr, hi);
|
||||
|
||||
var re = (double[])signal.Clone();
|
||||
var im = new double[n];
|
||||
Fourier.Forward(re, im);
|
||||
Assert.LessOrEqual(MaxError(re.AsSpan(0, bins).ToArray(), im.AsSpan(0, bins).ToArray(), hr, hi), 1e-9);
|
||||
|
||||
var back = new double[n];
|
||||
Fourier.InverseReal(hr, hi, back);
|
||||
for (var i = 0; i < n; i++) Assert.Approximately(signal[i], back[i], 1e-9);
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[Case(64, 64)]
|
||||
[Case(48, 36)]
|
||||
[Case(256, 160)]
|
||||
public void TwoDimensionalRoundTripAndShiftTheorem(int width, int height)
|
||||
{
|
||||
var (re, im) = RandomSignal(width * height, seed: width + height);
|
||||
var (r0, i0) = ((double[])re.Clone(), (double[])im.Clone());
|
||||
Fourier.Forward2D(re, im, width, height);
|
||||
// A unit impulse at (1, 0) transforms to e^(−2πiu/W) on every row: check one bin of a separate impulse.
|
||||
var dr = new double[width * height];
|
||||
var di = new double[width * height];
|
||||
dr[1] = 1;
|
||||
Fourier.Forward2D(dr, di, width, height);
|
||||
var (s, c) = double.SinCos(-2 * double.Pi * 3 / width);
|
||||
Assert.Approximately(c, dr[2 * width + 3], 1e-12);
|
||||
Assert.Approximately(s, di[2 * width + 3], 1e-12);
|
||||
|
||||
Fourier.Inverse2D(re, im, width, height);
|
||||
Assert.LessOrEqual(MaxError(r0, i0, re, im), 1e-5);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void ParsevalHolds()
|
||||
{
|
||||
const int n = 512;
|
||||
var (re, im) = RandomSignal(n, seed: 5);
|
||||
double time = 0, freq = 0;
|
||||
for (var i = 0; i < n; i++) time += re[i] * re[i] + im[i] * im[i];
|
||||
Fourier.Forward(re, im);
|
||||
for (var i = 0; i < n; i++) freq += re[i] * re[i] + im[i] * im[i];
|
||||
Assert.Approximately(time, freq / n, 1e-9 * time);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void WindowsHaveExpectedShape()
|
||||
{
|
||||
var hann = new double[9];
|
||||
Fourier.Hann(hann);
|
||||
Assert.Approximately(0, hann[0], 1e-15);
|
||||
Assert.Approximately(1, hann[4], 1e-15);
|
||||
Assert.Approximately(0.5, hann[2], 1e-12);
|
||||
Assert.Approximately(hann[1], hann[7], 1e-15);
|
||||
|
||||
var rect = new double[9];
|
||||
Fourier.Tukey(rect, 0);
|
||||
Assert.True(rect.All(v => v == 1));
|
||||
|
||||
var tukey = new double[101];
|
||||
Fourier.Tukey(tukey, 0.5);
|
||||
Assert.Approximately(0, tukey[0], 1e-15);
|
||||
Assert.Equal(1.0, tukey[25]);
|
||||
Assert.Equal(1.0, tukey[75]);
|
||||
// Mid-taper (x = 0.125) is at half height; the flanks rise monotonically and mirror each other.
|
||||
Assert.InRange(tukey[12], 0.45, 0.5);
|
||||
Assert.InRange(tukey[13], 0.5, 0.55);
|
||||
Assert.Monotonic(tukey.Take(26).ToArray());
|
||||
for (var i = 0; i < 101; i++) Assert.Approximately(tukey[i], tukey[100 - i], 1e-15);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void PlansAreCached() => Assert.Same(Fourier.Plan(96), Fourier.Plan(96));
|
||||
|
||||
private static (double[] Re, double[] Im) RandomSignal(int n, int seed)
|
||||
{
|
||||
var random = new Random(seed);
|
||||
var re = new double[n];
|
||||
var im = new double[n];
|
||||
for (var i = 0; i < n; i++)
|
||||
{
|
||||
re[i] = random.NextDouble() * 2 - 1;
|
||||
im[i] = random.NextDouble() * 2 - 1;
|
||||
}
|
||||
return (re, im);
|
||||
}
|
||||
|
||||
private static (double[] Re, double[] Im) Dft(double[] re, double[] im)
|
||||
{
|
||||
var n = re.Length;
|
||||
var or = new double[n];
|
||||
var oi = new double[n];
|
||||
for (var k = 0; k < n; k++)
|
||||
{
|
||||
double sr = 0, si = 0;
|
||||
for (var t = 0; t < n; t++)
|
||||
{
|
||||
var (s, c) = double.SinCos(-2 * double.Pi * ((long)k * t % n) / n);
|
||||
sr += re[t] * c - im[t] * s;
|
||||
si += re[t] * s + im[t] * c;
|
||||
}
|
||||
or[k] = sr;
|
||||
oi[k] = si;
|
||||
}
|
||||
return (or, oi);
|
||||
}
|
||||
|
||||
private static double MaxError(double[] ar, double[] ai, double[] br, double[] bi)
|
||||
{
|
||||
double max = 0;
|
||||
for (var i = 0; i < ar.Length; i++) max = double.Max(max, double.Max(double.Abs(ar[i] - br[i]), double.Abs(ai[i] - bi[i])));
|
||||
return max;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,119 @@
|
||||
using Titano.Core.Imaging;
|
||||
using Titano.Core.Motion;
|
||||
using Titano.Testing;
|
||||
|
||||
namespace Titano.Core.Tests.Motion;
|
||||
|
||||
public sealed class FrameInterpolatorTests
|
||||
{
|
||||
private const int Base = 256;
|
||||
private const int Frame = 160;
|
||||
private const int Margin = 16;
|
||||
|
||||
private readonly TestContext _context;
|
||||
|
||||
public FrameInterpolatorTests(TestContext context) => _context = context;
|
||||
|
||||
[Test]
|
||||
public void EndpointsReproduceTheKeyFrames()
|
||||
{
|
||||
var texture = SyntheticImages.Natural(Base, seed: 13);
|
||||
using var a = Shifted(texture, 0, 0);
|
||||
using var b = Shifted(texture, 3, -1.5);
|
||||
using var interpolator = new FrameInterpolator(FlowQuality.Balanced);
|
||||
using var output = new ImageBuffer(Frame, Frame);
|
||||
interpolator.Interpolate(a, b, 0, output);
|
||||
Assert.True(a.Data.SequenceEqual(output.Data));
|
||||
interpolator.Interpolate(a, b, 1, output);
|
||||
Assert.True(b.Data.SequenceEqual(output.Data));
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[Case(0.5)]
|
||||
[Case(0.25)]
|
||||
public void TranslationIsInterpolatedAlongTheMotion(double t)
|
||||
{
|
||||
const double dx = 4, dy = -2;
|
||||
var texture = SyntheticImages.Natural(Base, seed: 13);
|
||||
using var a = Shifted(texture, 0, 0);
|
||||
using var b = Shifted(texture, dx, dy);
|
||||
using var truth = Shifted(texture, t * dx, t * dy);
|
||||
using var interpolator = new FrameInterpolator();
|
||||
using var output = new ImageBuffer(Frame, Frame);
|
||||
interpolator.Interpolate(a, b, t, output);
|
||||
var psnr = SyntheticImages.Psnr(truth.Plane(1), output.Plane(1), Frame, Margin, Margin, Frame - Margin, Frame - Margin);
|
||||
|
||||
using var fade = new ImageBuffer(Frame, Frame);
|
||||
for (var i = 0; i < fade.Data.Length; i++) fade.Data[i] = (float)((1 - t) * a.Data[i] + t * b.Data[i]);
|
||||
var fadePsnr = SyntheticImages.Psnr(truth.Plane(1), fade.Plane(1), Frame, Margin, Margin, Frame - Margin, Frame - Margin);
|
||||
_context.Log($"t = {t}: interpolated {psnr:F1} dB, cross-fade {fadePsnr:F1} dB");
|
||||
Assert.GreaterOrEqual(psnr, 35);
|
||||
Assert.Greater(psnr, fadePsnr + 10);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void OcclusionReasoningPicksTheVisibleFrame()
|
||||
{
|
||||
// Exact flows: the square moves 12 px right; at t = 0.5 a 6 px strip behind it is visible only in B
|
||||
// and the strip ahead of it shows the square, which must be fetched along the square's motion.
|
||||
var background = SyntheticImages.Natural(Base, seed: 3);
|
||||
var foreground = SyntheticImages.Noise(Base, 1.2, seed: 4);
|
||||
using var a = Composite(background, foreground, 50);
|
||||
using var b = Composite(background, foreground, 62);
|
||||
using var truth = Composite(background, foreground, 56);
|
||||
using var forward = new MotionField(Frame, Frame, 1);
|
||||
using var backward = new MotionField(Frame, Frame, 1);
|
||||
for (var y = 50; y < 98; y++)
|
||||
{
|
||||
forward.U.Slice(y * Frame + 50, 48).Fill(12);
|
||||
backward.U.Slice(y * Frame + 62, 48).Fill(-12);
|
||||
}
|
||||
using var handled = new ImageBuffer(Frame, Frame);
|
||||
using var unweighted = new ImageBuffer(Frame, Frame);
|
||||
FrameInterpolator.Synthesize(a, b, forward, backward, 0.5, handled);
|
||||
FrameInterpolator.Synthesize(a, b, forward, backward, 0.5, unweighted, occlusionThreshold: 1e9);
|
||||
// Rows through the object, columns around its trailing and leading edges.
|
||||
var withWeights = SyntheticImages.Psnr(truth.Plane(1), handled.Plane(1), Frame, 36, 50, 124, 98);
|
||||
var without = SyntheticImages.Psnr(truth.Plane(1), unweighted.Plane(1), Frame, 36, 50, 124, 98);
|
||||
_context.Log($"exact flows, object region: occlusion-aware {withWeights:F1} dB, without sample weighting {without:F1} dB");
|
||||
Assert.GreaterOrEqual(withWeights, 42);
|
||||
Assert.Greater(withWeights, without + 10);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void MovingObjectIsInterpolatedWithEstimatedFlow()
|
||||
{
|
||||
var background = SyntheticImages.Natural(Base, seed: 3);
|
||||
var foreground = SyntheticImages.Noise(Base, 1.2, seed: 4);
|
||||
using var a = Composite(background, foreground, 50);
|
||||
using var b = Composite(background, foreground, 62);
|
||||
using var truth = Composite(background, foreground, 56);
|
||||
using var interpolator = new FrameInterpolator();
|
||||
using var output = new ImageBuffer(Frame, Frame);
|
||||
interpolator.Interpolate(a, b, 0.5, output);
|
||||
using var fade = new ImageBuffer(Frame, Frame);
|
||||
for (var i = 0; i < fade.Data.Length; i++) fade.Data[i] = 0.5f * (a.Data[i] + b.Data[i]);
|
||||
var psnr = SyntheticImages.Psnr(truth.Plane(1), output.Plane(1), Frame, 36, 50, 124, 98);
|
||||
var fadePsnr = SyntheticImages.Psnr(truth.Plane(1), fade.Plane(1), Frame, 36, 50, 124, 98);
|
||||
_context.Log($"estimated flows, object region: {psnr:F1} dB, cross-fade {fadePsnr:F1} dB");
|
||||
Assert.GreaterOrEqual(psnr, 33);
|
||||
Assert.Greater(psnr, fadePsnr + 5);
|
||||
}
|
||||
|
||||
private static ImageBuffer Shifted(double[] texture, double dx, double dy)
|
||||
{
|
||||
var shifted = dx == 0 && dy == 0 ? texture : SyntheticImages.Shift(texture, Base, dx, dy);
|
||||
return SyntheticImages.ToRgb(SyntheticImages.Crop(shifted, Base, 48, 48, Frame, Frame), Frame, Frame);
|
||||
}
|
||||
|
||||
/// <summary>Static background with a 48×48 textured square whose left edge is at <paramref name="x0"/>; the square carries its texture along.</summary>
|
||||
private static ImageBuffer Composite(double[] background, double[] foreground, int x0)
|
||||
{
|
||||
var plane = SyntheticImages.Crop(background, Base, 0, 0, Frame, Frame);
|
||||
for (var y = 50; y < 98; y++)
|
||||
{
|
||||
for (var x = 0; x < 48; x++) plane[y * Frame + x0 + x] = (float)(0.3 + 0.8 * (foreground[y * Base + x] - 0.5));
|
||||
}
|
||||
return SyntheticImages.ToRgb(plane, Frame, Frame);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,111 @@
|
||||
using Titano.Core.Imaging;
|
||||
using Titano.Core.Motion;
|
||||
using Titano.Testing;
|
||||
|
||||
namespace Titano.Core.Tests.Motion;
|
||||
|
||||
public sealed class MotionBlurTests
|
||||
{
|
||||
private const int Size = 128;
|
||||
|
||||
private readonly TestContext _context;
|
||||
|
||||
public MotionBlurTests(TestContext context) => _context = context;
|
||||
|
||||
[Theory]
|
||||
[Case(180.0, 90.0, 0.4330127018922193)]
|
||||
[Case(180.0, 0.0, 0.5)]
|
||||
[Case(360.0, 0.0, 1.0)]
|
||||
[Case(180.0, 180.0, 0.0)]
|
||||
[Case(180.0, 270.0, 0.0)]
|
||||
[Case(90.0, 54.0, 0.2)]
|
||||
public void BlurFractionComposesShutterAngles(double target, double real, double expected) =>
|
||||
Assert.Approximately(expected, ShutterAngle.BlurFraction(target, real), 1e-12);
|
||||
|
||||
[Test]
|
||||
public void RealShutterAngleFromExposure()
|
||||
{
|
||||
Assert.Approximately(180, ShutterAngle.FromExposure(1, 2), 1e-12);
|
||||
Assert.Approximately(3.6, ShutterAngle.FromExposure(1 / 250.0, 0.4), 1e-12);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void ZeroVectorsLeaveTheImageIdentical()
|
||||
{
|
||||
using var source = Texture();
|
||||
using var motion = new MotionField(Size, Size, 2);
|
||||
using var output = new ImageBuffer(Size, Size);
|
||||
new MotionBlurRenderer().Render(source, motion, 0.5, output);
|
||||
Assert.True(source.Data.SequenceEqual(output.Data));
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void PointBlursIntoASegmentWithItsEnergy()
|
||||
{
|
||||
using var source = new ImageBuffer(Size, Size, 1);
|
||||
source[0, 64, 64] = 1f;
|
||||
using var motion = new MotionField(Size, Size, 4);
|
||||
motion.Fill(20, 0);
|
||||
using var output = new ImageBuffer(Size, Size, 1);
|
||||
new MotionBlurRenderer().Render(source, motion, 0.5, output);
|
||||
|
||||
double total = 0;
|
||||
var columns = new HashSet<int>();
|
||||
for (var y = 0; y < Size; y++)
|
||||
{
|
||||
for (var x = 0; x < Size; x++)
|
||||
{
|
||||
var value = output[0, x, y];
|
||||
total += value;
|
||||
if (value <= 1e-6f) continue;
|
||||
Assert.Equal(64, y);
|
||||
columns.Add(x);
|
||||
}
|
||||
}
|
||||
_context.Log($"point energy after blur {total:F6}, segment columns {columns.Min()}..{columns.Max()}");
|
||||
Assert.Approximately(1, total, 1e-4);
|
||||
Assert.InRange(columns.Min(), 58, 60);
|
||||
Assert.InRange(columns.Max(), 68, 70);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void EnergyIsPreservedOnTexture()
|
||||
{
|
||||
using var source = Texture();
|
||||
using var motion = new MotionField(Size, Size, 2);
|
||||
for (var j = 0; j < motion.Rows; j++)
|
||||
for (var i = 0; i < motion.Columns; i++)
|
||||
{
|
||||
// A smooth swirl: magnitude up to ~6 px.
|
||||
var k = j * motion.Columns + i;
|
||||
motion.U[k] = (float)(6 * double.Sin(j * 0.1));
|
||||
motion.V[k] = (float)(4 * double.Cos(i * 0.08));
|
||||
}
|
||||
using var output = new ImageBuffer(Size, Size);
|
||||
new MotionBlurRenderer().Render(source, motion, 1.0, output);
|
||||
for (var c = 0; c < 3; c++)
|
||||
{
|
||||
var before = Mean(source.Plane(c), 16);
|
||||
var after = Mean(output.Plane(c), 16);
|
||||
_context.Log($"channel {c}: mean {before:F6} → {after:F6} ({(after - before) / before:P3})");
|
||||
Assert.Approximately(before, after, 2e-3 * before);
|
||||
}
|
||||
Assert.False(source.Data.SequenceEqual(output.Data));
|
||||
}
|
||||
|
||||
private static double Mean(ReadOnlySpan<float> plane, int margin)
|
||||
{
|
||||
double sum = 0;
|
||||
var n = 0;
|
||||
for (var y = margin; y < Size - margin; y++)
|
||||
for (var x = margin; x < Size - margin; x++)
|
||||
{
|
||||
sum += plane[y * Size + x];
|
||||
n++;
|
||||
}
|
||||
return sum / n;
|
||||
}
|
||||
|
||||
private static ImageBuffer Texture() =>
|
||||
SyntheticImages.ToRgb(SyntheticImages.Crop(SyntheticImages.Natural(Size, seed: 31), Size, 0, 0, Size, Size), Size, Size);
|
||||
}
|
||||
@@ -0,0 +1,155 @@
|
||||
using Titano.Core.Imaging;
|
||||
using Titano.Core.Imaging.Geometry;
|
||||
using Titano.Core.Motion;
|
||||
using Titano.Testing;
|
||||
|
||||
namespace Titano.Core.Tests.Motion;
|
||||
|
||||
public sealed class OpticalFlowTests
|
||||
{
|
||||
private const int Base = 256;
|
||||
private const int Frame = 192;
|
||||
private const int Margin = 16;
|
||||
|
||||
private readonly TestContext _context;
|
||||
|
||||
public OpticalFlowTests(TestContext context) => _context = context;
|
||||
|
||||
[Theory]
|
||||
[Case(FlowQuality.Draft)]
|
||||
[Case(FlowQuality.Balanced)]
|
||||
[Case(FlowQuality.Best)]
|
||||
public void TranslationEndPointErrorBelowAThirdOfAPixel(FlowQuality quality)
|
||||
{
|
||||
const double dx = 2.3, dy = -1.7;
|
||||
var texture = SyntheticImages.Natural(Base, seed: 11);
|
||||
using var a = SyntheticImages.ToRgb(SyntheticImages.Crop(texture, Base, 32, 32, Frame, Frame), Frame, Frame);
|
||||
using var b = SyntheticImages.ToRgb(SyntheticImages.Crop(SyntheticImages.Shift(texture, Base, dx, dy), Base, 32, 32, Frame, Frame), Frame, Frame);
|
||||
using var engine = new OpticalFlowEngine(quality);
|
||||
using var field = engine.Compute(a, b);
|
||||
var epe = MeanEndPointError(field, (_, _) => (dx, dy));
|
||||
_context.Log($"{quality}: step {field.Step}, mean EPE {epe:F4} px");
|
||||
Assert.Less(epe, 0.3);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void RotationEndPointErrorBelowOnePixel()
|
||||
{
|
||||
var angle = 3.0 * double.Pi / 180;
|
||||
var texture = SyntheticImages.Natural(Base, seed: 5);
|
||||
using var baseImage = SyntheticImages.ToRgb(SyntheticImages.Crop(texture, Base, 0, 0, Base, Base), Base, Base);
|
||||
using var rotated = new ImageBuffer(Base, Base);
|
||||
const double c = (Base - 1) / 2.0;
|
||||
// rotated(x) = base(R⁻¹(x − c) + c): content turns by +angle about the centre.
|
||||
GeometryStage.Warp(baseImage, rotated, Affine2D.About(Affine2D.Rotation(-angle), c, c));
|
||||
using var a = Crop(baseImage, 32);
|
||||
using var b = Crop(rotated, 32);
|
||||
using var engine = new OpticalFlowEngine(FlowQuality.Best);
|
||||
using var field = engine.Compute(a, b);
|
||||
var truth = Affine2D.About(Affine2D.Rotation(angle), c - 32, c - 32);
|
||||
var epe = MeanEndPointError(field, (x, y) =>
|
||||
{
|
||||
var (tx, ty) = truth.Apply(x, y);
|
||||
return (tx - x, ty - y);
|
||||
});
|
||||
_context.Log($"rotation 3°: mean EPE {epe:F4} px");
|
||||
Assert.Less(epe, 1.0);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void ForwardBackwardErrorIsSmallForConsistentMotion()
|
||||
{
|
||||
var texture = SyntheticImages.Natural(Base, seed: 2);
|
||||
using var a = SyntheticImages.ToRgb(SyntheticImages.Crop(texture, Base, 32, 32, Frame, Frame), Frame, Frame);
|
||||
using var b = SyntheticImages.ToRgb(SyntheticImages.Crop(SyntheticImages.Shift(texture, Base, -1.5, 0.75), Base, 32, 32, Frame, Frame), Frame, Frame);
|
||||
using var engine = new OpticalFlowEngine(FlowQuality.Balanced);
|
||||
var (forward, backward) = engine.ComputeBidirectional(a, b);
|
||||
using (forward)
|
||||
using (backward)
|
||||
{
|
||||
Assert.True(forward.HasConsistency);
|
||||
var stats = forward.Statistics(reliableError: 0.5);
|
||||
_context.Log($"reliable {stats.ReliableFraction:P1}, mean |w| {stats.MeanMagnitude:F3}");
|
||||
Assert.Greater(stats.ReliableFraction, 0.85);
|
||||
Assert.Approximately(1.677, stats.MedianMagnitude, 0.1);
|
||||
Assert.Less(forward.SampleError(96, 96), 0.2);
|
||||
var (bu, bv) = backward.Sample(96, 96);
|
||||
Assert.Within(1.5, -0.75, bu, bv, 0.2);
|
||||
}
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void FieldSamplingHistogramAndStatistics()
|
||||
{
|
||||
using var field = new MotionField(9, 5, 4);
|
||||
Assert.Equal(3, field.Columns);
|
||||
Assert.Equal(2, field.Rows);
|
||||
for (var j = 0; j < field.Rows; j++)
|
||||
for (var i = 0; i < field.Columns; i++)
|
||||
{
|
||||
field.U[j * field.Columns + i] = i;
|
||||
field.V[j * field.Columns + i] = 2 * j;
|
||||
}
|
||||
var (u, v) = field.Sample(6, 2);
|
||||
Assert.Approximately(1.5, u, 1e-6);
|
||||
Assert.Approximately(1, v, 1e-6);
|
||||
Assert.True(float.IsNaN(field.SampleError(0, 0)));
|
||||
|
||||
field.Fill(3, 4);
|
||||
var histogram = field.MagnitudeHistogram(10, 10);
|
||||
Assert.Equal(6, histogram[5]);
|
||||
Assert.Equal(6, field.MagnitudeHistogram(4, 2)[3]);
|
||||
var stats = field.Statistics();
|
||||
Assert.Approximately(5, stats.MeanMagnitude, 1e-6);
|
||||
Assert.Approximately(5, stats.P95Magnitude, 1e-6);
|
||||
Assert.Approximately(3, stats.MeanU, 1e-6);
|
||||
Assert.Equal(1.0, stats.ReliableFraction);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void PyramidLevelsHalveAndPreserveMean()
|
||||
{
|
||||
var texture = SyntheticImages.Crop(SyntheticImages.Noise(Base, 1.5, seed: 8), Base, 0, 0, 101, 75);
|
||||
using var pyramid = new GrayPyramid(101, 75, GrayPyramid.LevelsFor(101, 75));
|
||||
Assert.Equal(3, pyramid.Levels);
|
||||
pyramid.Build(texture);
|
||||
Assert.Equal(51, pyramid.LevelWidth(1));
|
||||
Assert.Equal(38, pyramid.LevelHeight(1));
|
||||
Assert.Equal(26, pyramid.LevelWidth(2));
|
||||
var mean0 = pyramid.Level(0).ToArray().Average();
|
||||
var mean2 = pyramid.Level(2).ToArray().Average();
|
||||
Assert.Approximately(mean0, mean2, 0.02);
|
||||
|
||||
var flat = new float[64 * 64];
|
||||
flat.AsSpan().Fill(0.25f);
|
||||
using var constant = new GrayPyramid(64, 64, 3);
|
||||
constant.Build(flat);
|
||||
Assert.True(constant.Level(2).ToArray().All(x => x == 0.25f));
|
||||
}
|
||||
|
||||
private static double MeanEndPointError(MotionField field, Func<double, double, (double U, double V)> truth)
|
||||
{
|
||||
double sum = 0;
|
||||
var n = 0;
|
||||
for (var j = 0; j < field.Rows; j++)
|
||||
{
|
||||
for (var i = 0; i < field.Columns; i++)
|
||||
{
|
||||
double x = i * field.Step, y = j * field.Step;
|
||||
if (x < Margin || y < Margin || x >= Frame - Margin || y >= Frame - Margin) continue;
|
||||
var (tu, tv) = truth(x, y);
|
||||
var k = j * field.Columns + i;
|
||||
sum += double.Hypot(field.U[k] - tu, field.V[k] - tv);
|
||||
n++;
|
||||
}
|
||||
}
|
||||
return sum / n;
|
||||
}
|
||||
|
||||
private static ImageBuffer Crop(ImageBuffer source, int offset)
|
||||
{
|
||||
var crop = new ImageBuffer(Frame, Frame);
|
||||
GeometryStage.Warp(source, crop, Affine2D.Translation(offset, offset));
|
||||
return crop;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,83 @@
|
||||
using Titano.Core.Motion;
|
||||
using Titano.Testing;
|
||||
|
||||
namespace Titano.Core.Tests.Motion;
|
||||
|
||||
public sealed class PhaseCorrelatorTests
|
||||
{
|
||||
private const int Size = 256;
|
||||
private const int Patch = 128;
|
||||
|
||||
private readonly TestContext _context;
|
||||
|
||||
public PhaseCorrelatorTests(TestContext context) => _context = context;
|
||||
|
||||
[Theory]
|
||||
[Case("noise", 3.25, -1.6)]
|
||||
[Case("noise", 0.5, 0.5)]
|
||||
[Case("noise", -7.8, 2.1)]
|
||||
[Case("noise", 0.0, 0.0)]
|
||||
[Case("natural", 3.25, -1.6)]
|
||||
[Case("natural", 0.5, 0.5)]
|
||||
[Case("natural", -7.8, 2.1)]
|
||||
[Case("natural", 12.3, -9.45)]
|
||||
public void SubPixelErrorWithinTenthOfPixel(string texture, double dx, double dy)
|
||||
{
|
||||
var image = texture == "noise" ? SyntheticImages.Noise(Size, 0.8, seed: 7) : SyntheticImages.Natural(Size, seed: 7);
|
||||
var shifted = SyntheticImages.Shift(image, Size, dx, dy);
|
||||
var reference = SyntheticImages.Crop(image, Size, 64, 64, Patch, Patch);
|
||||
var moving = SyntheticImages.Crop(shifted, Size, 64, 64, Patch, Patch);
|
||||
|
||||
var result = new PhaseCorrelator(Patch, Patch).Correlate(reference, moving);
|
||||
var error = double.Hypot(result.Dx - dx, result.Dy - dy);
|
||||
_context.Log($"{texture} ({dx}, {dy}) → ({result.Dx:F4}, {result.Dy:F4}) error {error:F4} px, confidence {result.Confidence:F3}, peak {result.Peak:F3}");
|
||||
Assert.LessOrEqual(error, 0.10);
|
||||
Assert.Greater(result.Confidence, 0.5);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void NonPowerOfTwoPatchesUseBluestein()
|
||||
{
|
||||
var image = SyntheticImages.Natural(Size, seed: 3);
|
||||
var shifted = SyntheticImages.Shift(image, Size, -2.4, 1.3);
|
||||
var reference = SyntheticImages.Crop(image, Size, 60, 70, 96, 80);
|
||||
var moving = SyntheticImages.Crop(shifted, Size, 60, 70, 96, 80);
|
||||
var result = new PhaseCorrelator(96, 80).Correlate(reference, moving);
|
||||
Assert.Within(-2.4, 1.3, result.Dx, result.Dy, 0.10);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void PatchesAreReadFromLargerPlanes()
|
||||
{
|
||||
var image = SyntheticImages.Noise(Size, 1.0, seed: 9);
|
||||
var shifted = SyntheticImages.Shift(image, Size, 1.75, -0.25);
|
||||
var a = SyntheticImages.Crop(image, Size, 0, 0, Size, Size);
|
||||
var b = SyntheticImages.Crop(shifted, Size, 0, 0, Size, Size);
|
||||
var result = new PhaseCorrelator(64, 64).Correlate(a, b, Size, 100, 40);
|
||||
Assert.Within(1.75, -0.25, result.Dx, result.Dy, 0.10);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void UnrelatedContentHasLowConfidence()
|
||||
{
|
||||
var a = SyntheticImages.Crop(SyntheticImages.Noise(Size, 0.8, seed: 1), Size, 0, 0, Patch, Patch);
|
||||
var b = SyntheticImages.Crop(SyntheticImages.Noise(Size, 0.8, seed: 2), Size, 0, 0, Patch, Patch);
|
||||
var result = new PhaseCorrelator(Patch, Patch).Correlate(a, b);
|
||||
_context.Log($"confidence {result.Confidence:F3}, peak {result.Peak:F3}");
|
||||
Assert.Less(result.Confidence, 0.4);
|
||||
Assert.Less(result.Peak, 0.2);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void MaxShiftLimitsTheSearch()
|
||||
{
|
||||
var image = SyntheticImages.Noise(Size, 0.8, seed: 4);
|
||||
var shifted = SyntheticImages.Shift(image, Size, 20, 0);
|
||||
var a = SyntheticImages.Crop(image, Size, 64, 64, Patch, Patch);
|
||||
var b = SyntheticImages.Crop(shifted, Size, 64, 64, Patch, Patch);
|
||||
var free = new PhaseCorrelator(Patch, Patch).Correlate(a, b);
|
||||
Assert.Within(20, 0, free.Dx, free.Dy, 0.10);
|
||||
var limited = new PhaseCorrelator(Patch, Patch, new PhaseCorrelatorOptions { MaxShift = 8 }).Correlate(a, b);
|
||||
Assert.LessOrEqual(double.Abs(limited.Dx), 8.5);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,97 @@
|
||||
using Titano.Core.Motion;
|
||||
using Titano.Testing;
|
||||
|
||||
namespace Titano.Core.Tests.Motion;
|
||||
|
||||
public sealed class PlaneOpsTests
|
||||
{
|
||||
private const int Width = 37;
|
||||
private const int Height = 23;
|
||||
|
||||
[Theory]
|
||||
[Case(1)]
|
||||
[Case(2)]
|
||||
public void MedianFilterMatchesBruteForce(int radius)
|
||||
{
|
||||
var source = RandomPlane(seed: radius);
|
||||
var output = new float[source.Length];
|
||||
PlaneOps.MedianFilter(source, output, Width, Height, radius);
|
||||
for (var y = 0; y < Height; y++)
|
||||
{
|
||||
for (var x = 0; x < Width; x++)
|
||||
{
|
||||
var window = new List<float>();
|
||||
for (var dy = -radius; dy <= radius; dy++)
|
||||
for (var dx = -radius; dx <= radius; dx++)
|
||||
window.Add(source[int.Clamp(y + dy, 0, Height - 1) * Width + int.Clamp(x + dx, 0, Width - 1)]);
|
||||
window.Sort();
|
||||
Assert.Equal(window[window.Count / 2], output[y * Width + x]);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[Case(1)]
|
||||
[Case(3)]
|
||||
public void BoxFilterMatchesBruteForce(int radius)
|
||||
{
|
||||
var source = RandomPlane(seed: 10 + radius);
|
||||
var output = new float[source.Length];
|
||||
PlaneOps.BoxFilter(source, output, new float[source.Length], Width, Height, radius);
|
||||
for (var y = 0; y < Height; y++)
|
||||
{
|
||||
for (var x = 0; x < Width; x++)
|
||||
{
|
||||
double sum = 0;
|
||||
for (var dy = -radius; dy <= radius; dy++)
|
||||
for (var dx = -radius; dx <= radius; dx++)
|
||||
sum += source[int.Clamp(y + dy, 0, Height - 1) * Width + int.Clamp(x + dx, 0, Width - 1)];
|
||||
Assert.Approximately(sum / ((2 * radius + 1) * (2 * radius + 1)), output[y * Width + x], 1e-5);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void BinomialBlurKeepsConstantsAndMean()
|
||||
{
|
||||
var flat = new float[Width * Height];
|
||||
flat.AsSpan().Fill(0.7f);
|
||||
PlaneOps.Binomial5(flat, flat, new float[flat.Length], Width, Height);
|
||||
Assert.True(flat.All(v => double.Abs(v - 0.7) < 1e-6));
|
||||
|
||||
var impulse = new float[Width * Height];
|
||||
impulse[11 * Width + 17] = 1;
|
||||
var blurred = new float[impulse.Length];
|
||||
PlaneOps.Binomial5(impulse, blurred, new float[impulse.Length], Width, Height);
|
||||
Assert.Approximately(1, blurred.Sum(v => (double)v), 1e-6);
|
||||
Assert.Approximately(36.0 / 256, blurred[11 * Width + 17], 1e-7);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void SelectionAndMedian()
|
||||
{
|
||||
var values = new float[] { 5, 1, 4, 2, 3 };
|
||||
Assert.Equal(3f, PlaneOps.Median(values));
|
||||
Assert.Equal(2.5f, PlaneOps.Median(new float[] { 4, 1, 3, 2 }));
|
||||
Assert.Equal(1f, PlaneOps.Select(new float[] { 3, 1, 2 }, 0));
|
||||
Assert.Equal(7f, PlaneOps.Median(new float[] { 7 }));
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void BilinearIsExactAtPixelCentresAndClamps()
|
||||
{
|
||||
var plane = RandomPlane(seed: 3);
|
||||
Assert.Equal(plane[5 * Width + 9], PlaneOps.Bilinear(plane, Width, Height, 9, 5));
|
||||
Assert.Equal(plane[0], PlaneOps.Bilinear(plane, Width, Height, -3, -8));
|
||||
var mid = 0.5f * (plane[5 * Width + 9] + plane[5 * Width + 10]);
|
||||
Assert.Approximately(mid, PlaneOps.Bilinear(plane, Width, Height, 9.5f, 5), 1e-6);
|
||||
}
|
||||
|
||||
private static float[] RandomPlane(int seed)
|
||||
{
|
||||
var random = new Random(seed);
|
||||
var plane = new float[Width * Height];
|
||||
for (var i = 0; i < plane.Length; i++) plane[i] = (float)random.NextDouble();
|
||||
return plane;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,171 @@
|
||||
using Titano.Core.Imaging;
|
||||
using Titano.Core.Imaging.Geometry;
|
||||
using Titano.Core.Motion;
|
||||
using Titano.Testing;
|
||||
|
||||
namespace Titano.Core.Tests.Motion;
|
||||
|
||||
public sealed class StabilizerTests
|
||||
{
|
||||
private const int Width = 256;
|
||||
private const int Height = 192;
|
||||
private const int Frames = 48;
|
||||
|
||||
private readonly TestContext _context;
|
||||
|
||||
public StabilizerTests(TestContext context) => _context = context;
|
||||
|
||||
[Test]
|
||||
public void TexturelessFramesReportNoShakeAndNoCorrection()
|
||||
{
|
||||
var random = new Random(17);
|
||||
using var stabilizer = new Stabilizer(128, 128);
|
||||
using var frame = new ImageBuffer(128, 128);
|
||||
for (var k = 0; k < 20; k++)
|
||||
{
|
||||
var data = frame.Data;
|
||||
for (var i = 0; i < data.Length; i++) data[i] = 0.3f + 0.004f * (float)Gaussian(random);
|
||||
Assert.False(stabilizer.AddFrame(frame).Estimated);
|
||||
}
|
||||
var result = stabilizer.Solve();
|
||||
_context.Log($"textureless shake {result.ShakeRms:F4} px, crop scale {result.CropScale:F4}");
|
||||
Assert.LessOrEqual(result.ShakeRms, 0.1);
|
||||
Assert.False(result.Recommended);
|
||||
Assert.Equal(1.0, result.CropScale);
|
||||
Assert.True(result.Corrections.All(c => c == Affine2D.Identity));
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void JitterIsReducedByAtLeastEightyPercent()
|
||||
{
|
||||
var random = new Random(23);
|
||||
var cameras = new Affine2D[Frames];
|
||||
for (var k = 0; k < Frames; k++) cameras[k] = Camera(2.0 * Gaussian(random), 2.0 * Gaussian(random), 0.3 * Gaussian(random), pan: 0, k);
|
||||
var result = Stabilize(cameras, out var motionError);
|
||||
var before = Jitter(cameras, null);
|
||||
var after = Jitter(cameras, result.Corrections);
|
||||
var reduction = 1 - after / before;
|
||||
_context.Log($"frame-to-frame jitter {before:F3} → {after:F3} px ({reduction:P1}); motion error {motionError:F4} px; shake {result.ShakeRms:F3} px; crop cost {result.CropCost:P1}");
|
||||
Assert.GreaterOrEqual(reduction, 0.8);
|
||||
Assert.Less(motionError, 0.1);
|
||||
Assert.True(result.Recommended);
|
||||
Assert.Greater(result.ShakeRms, 1.0);
|
||||
Assert.InRange(result.CropCost, 0.01, 0.3);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void IntentionalPanSurvivesStabilisation()
|
||||
{
|
||||
const double pan = 1.5;
|
||||
var random = new Random(29);
|
||||
var cameras = new Affine2D[Frames];
|
||||
for (var k = 0; k < Frames; k++) cameras[k] = Camera(1.5 * Gaussian(random), 1.5 * Gaussian(random), 0.2 * Gaussian(random), pan, k);
|
||||
var result = Stabilize(cameras, out _);
|
||||
|
||||
// The stabilised view still follows the pan: content drifts left by `pan` px per frame.
|
||||
var (bx, by) = cameras[0].Apply(Width / 2.0, Height / 2.0);
|
||||
(double X, double Y) Track(int k)
|
||||
{
|
||||
var (x, y) = cameras[k].Invert().Apply(bx, by);
|
||||
return result.Corrections[k].Apply(x, y);
|
||||
}
|
||||
var (sx, sy) = Track(0);
|
||||
var (ex, ey) = Track(Frames - 1);
|
||||
var velocity = (ex - sx) / (Frames - 1);
|
||||
_context.Log($"stabilised velocity {velocity:F3} px/frame (pan {-pan}), vertical drift {ey - sy:F3} px");
|
||||
Assert.Approximately(-pan, velocity, 0.1);
|
||||
var reduction = 1 - Jitter(cameras, result.Corrections, removeMean: true) / Jitter(cameras, null, removeMean: true);
|
||||
Assert.GreaterOrEqual(reduction, 0.8);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void SmootherKeepsLinesAndEnds()
|
||||
{
|
||||
var line = Enumerable.Range(0, 30).Select(i => 3 + 0.5 * i).ToArray();
|
||||
var smoothed = PathSmoother.LocalLinear(line, 5);
|
||||
for (var i = 0; i < line.Length; i++) Assert.Approximately(line[i], smoothed[i], 1e-9);
|
||||
// Frame-rate jitter (alternating ±1) is removed in the interior and strongly attenuated at the ends.
|
||||
var noisy = Enumerable.Range(0, 200).Select(i => i % 2 == 0 ? 1.0 : -1.0).ToArray();
|
||||
var flat = PathSmoother.LocalLinear(noisy, 8);
|
||||
var interior = flat.Skip(24).SkipLast(24).Max(double.Abs);
|
||||
var ends = flat.Max(double.Abs);
|
||||
_context.Log($"interior {interior:E2}, ends {ends:E2}");
|
||||
Assert.Less(interior, 0.01);
|
||||
Assert.Less(ends, 0.2);
|
||||
}
|
||||
|
||||
/// <summary>Frame pixel → base-texture coordinate: jitter translation and rotation about the frame centre, plus a pan.</summary>
|
||||
private static Affine2D Camera(double tx, double ty, double degrees, double pan, int k) =>
|
||||
Affine2D.Translation(100 + pan * k, 150)
|
||||
* Affine2D.About(Affine2D.Rotation(degrees * double.Pi / 180), (Width - 1) / 2.0, (Height - 1) / 2.0)
|
||||
* Affine2D.Translation(tx, ty);
|
||||
|
||||
private static StabilizationResult Stabilize(Affine2D[] cameras, out double motionError)
|
||||
{
|
||||
const int Base = 512;
|
||||
using var texture = SyntheticImages.ToRgb(SyntheticImages.Crop(SyntheticImages.Natural(Base, seed: 41), Base, 0, 0, Base, Base), Base, Base);
|
||||
using var frame = new ImageBuffer(Width, Height);
|
||||
using var stabilizer = new Stabilizer(Width, Height);
|
||||
double error = 0;
|
||||
var samples = 0;
|
||||
for (var k = 0; k < cameras.Length; k++)
|
||||
{
|
||||
GeometryStage.Warp(texture, frame, cameras[k]);
|
||||
var motion = stabilizer.AddFrame(frame);
|
||||
if (k == 0) continue;
|
||||
// True inter-frame map: previous frame → base → current frame.
|
||||
var truth = cameras[k].Invert() * cameras[k - 1];
|
||||
foreach (var (x, y) in GridPoints())
|
||||
{
|
||||
var (tx, ty) = truth.Apply(x, y);
|
||||
var (mx, my) = motion.Transform.Apply(x, y);
|
||||
error += double.Hypot(tx - mx, ty - my);
|
||||
samples++;
|
||||
}
|
||||
}
|
||||
motionError = error / samples;
|
||||
return stabilizer.Solve();
|
||||
}
|
||||
|
||||
/// <summary>RMS frame-to-frame displacement of fixed content points in the (corrected) frames.</summary>
|
||||
private static double Jitter(Affine2D[] cameras, IReadOnlyList<Affine2D>? corrections, bool removeMean = false)
|
||||
{
|
||||
var points = GridPoints().Select(p => cameras[0].Apply(p.X, p.Y)).ToArray();
|
||||
var steps = new List<(double X, double Y)>();
|
||||
for (var k = 1; k < cameras.Length; k++)
|
||||
{
|
||||
foreach (var (bx, by) in points)
|
||||
{
|
||||
var (x0, y0) = cameras[k - 1].Invert().Apply(bx, by);
|
||||
var (x1, y1) = cameras[k].Invert().Apply(bx, by);
|
||||
if (corrections is not null)
|
||||
{
|
||||
(x0, y0) = corrections[k - 1].Apply(x0, y0);
|
||||
(x1, y1) = corrections[k].Apply(x1, y1);
|
||||
}
|
||||
steps.Add((x1 - x0, y1 - y0));
|
||||
}
|
||||
}
|
||||
double mx = 0, my = 0;
|
||||
if (removeMean)
|
||||
{
|
||||
mx = steps.Average(s => s.X);
|
||||
my = steps.Average(s => s.Y);
|
||||
}
|
||||
return double.Sqrt(steps.Average(s => (s.X - mx) * (s.X - mx) + (s.Y - my) * (s.Y - my)));
|
||||
}
|
||||
|
||||
private static IEnumerable<(double X, double Y)> GridPoints()
|
||||
{
|
||||
for (var j = 1; j <= 3; j++)
|
||||
for (var i = 1; i <= 3; i++)
|
||||
yield return (Width * i / 4.0, Height * j / 4.0);
|
||||
}
|
||||
|
||||
private static double Gaussian(Random random)
|
||||
{
|
||||
var u1 = 1.0 - random.NextDouble();
|
||||
var u2 = random.NextDouble();
|
||||
return double.Sqrt(-2 * double.Log(u1)) * double.Cos(2 * double.Pi * u2);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,122 @@
|
||||
using Titano.Core.Imaging;
|
||||
using Titano.Core.Motion;
|
||||
|
||||
namespace Titano.Core.Tests.Motion;
|
||||
|
||||
/// <summary>Deterministic synthetic textures (periodic, band-limited) and exact sub-pixel shifts by Fourier phase ramp.</summary>
|
||||
internal static class SyntheticImages
|
||||
{
|
||||
/// <summary>Gaussian-filtered white noise: spectral envelope exp(−2π²σ²|f|²), mean 0.5, standard deviation 0.15.</summary>
|
||||
public static double[] Noise(int size, double sigma, int seed) =>
|
||||
Synthesize(size, seed, f => double.Exp(-2 * double.Pi * double.Pi * sigma * sigma * f * f));
|
||||
|
||||
/// <summary>Natural-image-like texture: amplitude ∝ 1/f^1.4 with a soft high-frequency roll-off.</summary>
|
||||
public static double[] Natural(int size, int seed) =>
|
||||
Synthesize(size, seed, f => f == 0 ? 0 : double.Pow(f * size, -1.4) * double.Exp(-f * f / (2 * 0.2 * 0.2)));
|
||||
|
||||
/// <summary>Periodic shift with sub-pixel accuracy: result(x, y) = image(x − dx, y − dy).</summary>
|
||||
public static double[] Shift(double[] image, int size, double dx, double dy)
|
||||
{
|
||||
var re = (double[])image.Clone();
|
||||
var im = new double[re.Length];
|
||||
Fourier.Forward2D(re, im, size, size);
|
||||
for (var v = 0; v < size; v++)
|
||||
{
|
||||
for (var u = 0; u < size; u++)
|
||||
{
|
||||
var (s, c) = double.SinCos(-2 * double.Pi * (Signed(u, size) * dx + Signed(v, size) * dy) / size);
|
||||
var i = v * size + u;
|
||||
(re[i], im[i]) = (re[i] * c - im[i] * s, re[i] * s + im[i] * c);
|
||||
}
|
||||
}
|
||||
Fourier.Inverse2D(re, im, size, size);
|
||||
return re;
|
||||
}
|
||||
|
||||
/// <summary>Copies a rectangle of a square periodic image into a float plane.</summary>
|
||||
public static float[] Crop(double[] image, int size, int x0, int y0, int width, int height)
|
||||
{
|
||||
var plane = new float[width * height];
|
||||
for (var y = 0; y < height; y++)
|
||||
{
|
||||
for (var x = 0; x < width; x++) plane[y * width + x] = (float)image[((y0 + y) % size) * size + (x0 + x) % size];
|
||||
}
|
||||
return plane;
|
||||
}
|
||||
|
||||
/// <summary>Single-channel buffer from a plane.</summary>
|
||||
public static ImageBuffer ToBuffer(float[] plane, int width, int height)
|
||||
{
|
||||
var buffer = new ImageBuffer(width, height, 1, clear: false);
|
||||
plane.AsSpan().CopyTo(buffer.Plane(0));
|
||||
return buffer;
|
||||
}
|
||||
|
||||
/// <summary>RGB buffer whose channels are scaled copies of a plane (distinct but correlated colours).</summary>
|
||||
public static ImageBuffer ToRgb(float[] plane, int width, int height)
|
||||
{
|
||||
var buffer = new ImageBuffer(width, height, 3, clear: false);
|
||||
for (var c = 0; c < 3; c++)
|
||||
{
|
||||
var dst = buffer.Plane(c);
|
||||
var gain = 0.6f + 0.2f * c;
|
||||
for (var i = 0; i < plane.Length; i++) dst[i] = plane[i] * gain;
|
||||
}
|
||||
return buffer;
|
||||
}
|
||||
|
||||
/// <summary>Peak signal-to-noise ratio in dB for unit peak over the window [x0, x1)×[y0, y1).</summary>
|
||||
public static double Psnr(ReadOnlySpan<float> a, ReadOnlySpan<float> b, int width, int x0, int y0, int x1, int y1)
|
||||
{
|
||||
double sum = 0;
|
||||
var n = 0;
|
||||
for (var y = y0; y < y1; y++)
|
||||
{
|
||||
for (var x = x0; x < x1; x++)
|
||||
{
|
||||
var d = a[y * width + x] - (double)b[y * width + x];
|
||||
sum += d * d;
|
||||
n++;
|
||||
}
|
||||
}
|
||||
var mse = sum / n;
|
||||
return mse == 0 ? double.PositiveInfinity : 10 * double.Log10(1 / mse);
|
||||
}
|
||||
|
||||
private static double[] Synthesize(int size, int seed, Func<double, double> envelope)
|
||||
{
|
||||
var random = new Random(seed);
|
||||
var re = new double[size * size];
|
||||
var im = new double[size * size];
|
||||
for (var v = 0; v < size; v++)
|
||||
{
|
||||
for (var u = 0; u < size; u++)
|
||||
{
|
||||
// Nyquist bins stay empty so the phase-ramp shift is exact for a real image.
|
||||
if (u == size / 2 || v == size / 2) continue;
|
||||
double fx = Signed(u, size) / (double)size, fy = Signed(v, size) / (double)size;
|
||||
var a = envelope(double.Sqrt(fx * fx + fy * fy));
|
||||
re[v * size + u] = a * Gaussian(random);
|
||||
im[v * size + u] = a * Gaussian(random);
|
||||
}
|
||||
}
|
||||
re[0] = im[0] = 0;
|
||||
Fourier.Inverse2D(re, im, size, size);
|
||||
double mean = 0, sq = 0;
|
||||
foreach (var x in re) mean += x;
|
||||
mean /= re.Length;
|
||||
foreach (var x in re) sq += (x - mean) * (x - mean);
|
||||
var scale = 0.15 / double.Sqrt(sq / re.Length);
|
||||
for (var i = 0; i < re.Length; i++) re[i] = 0.5 + (re[i] - mean) * scale;
|
||||
return re;
|
||||
}
|
||||
|
||||
private static double Gaussian(Random random)
|
||||
{
|
||||
var u1 = 1.0 - random.NextDouble();
|
||||
var u2 = random.NextDouble();
|
||||
return double.Sqrt(-2 * double.Log(u1)) * double.Cos(2 * double.Pi * u2);
|
||||
}
|
||||
|
||||
private static int Signed(int index, int length) => index <= length / 2 ? index : index - length;
|
||||
}
|
||||
@@ -0,0 +1,194 @@
|
||||
using Titano.Core.Imaging;
|
||||
using Titano.Core.Motion;
|
||||
using Titano.Testing;
|
||||
|
||||
namespace Titano.Core.Tests.Motion;
|
||||
|
||||
public sealed class TemporalStackerTests
|
||||
{
|
||||
private const int Size = 96;
|
||||
|
||||
private readonly TestContext _context;
|
||||
|
||||
public TemporalStackerTests(TestContext context) => _context = context;
|
||||
|
||||
[Test]
|
||||
public void StarTrailLuminanceNeverDecreasesWithUnitDecay()
|
||||
{
|
||||
var random = new Random(5);
|
||||
using var stacker = new StarTrailStacker(1.0);
|
||||
using var frame = new ImageBuffer(Size, Size);
|
||||
var previous = new float[Size * Size];
|
||||
var current = new float[Size * Size];
|
||||
long steps = 0, nonDecreasing = 0;
|
||||
for (var k = 0; k < 40; k++)
|
||||
{
|
||||
NightFrame(frame, random, k);
|
||||
stacker.Add(frame);
|
||||
ColorSpace.Luminance(stacker.Result!, current);
|
||||
if (k > 0)
|
||||
{
|
||||
for (var i = 0; i < current.Length; i++)
|
||||
{
|
||||
steps++;
|
||||
if (current[i] >= previous[i]) nonDecreasing++;
|
||||
}
|
||||
}
|
||||
(previous, current) = (current, previous);
|
||||
}
|
||||
var fraction = nonDecreasing / (double)steps;
|
||||
_context.Log($"non-decreasing on {fraction:P3} of {steps} pixel steps");
|
||||
Assert.GreaterOrEqual(fraction, 0.99);
|
||||
Assert.Equal(40, stacker.Count);
|
||||
// The trail of the first star position is still lit after 40 frames.
|
||||
Assert.Greater(stacker.Result![1, StarX(0), StarY(0)], 0.5f);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void FiniteTrailsFadeToOnePercentOverTheirLength()
|
||||
{
|
||||
Assert.Equal(1.0, StarTrailStacker.DecayForTrailLength(double.PositiveInfinity));
|
||||
Assert.Equal(1.0, StarTrailStacker.DecayForTrailLength(0));
|
||||
var decay = StarTrailStacker.DecayForTrailLength(20);
|
||||
Assert.Approximately(0.01, double.Pow(decay, 20), 1e-12);
|
||||
|
||||
using var stacker = new StarTrailStacker(decay);
|
||||
using var lit = new ImageBuffer(8, 8, 1);
|
||||
using var dark = new ImageBuffer(8, 8, 1);
|
||||
lit[0, 3, 3] = 1f;
|
||||
stacker.Add(lit);
|
||||
for (var k = 0; k < 20; k++) stacker.Add(dark);
|
||||
Assert.Approximately(0.01, stacker.Result![0, 3, 3], 1e-5);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void MedianRemovesATransientOutlierFrame()
|
||||
{
|
||||
var plane = SyntheticImages.Crop(SyntheticImages.Natural(128, seed: 12), 128, 0, 0, Size, Size);
|
||||
var random = new Random(8);
|
||||
using var stacker = new TemporalStacker(7, StackMode.Median);
|
||||
for (var k = 0; k < 7; k++)
|
||||
{
|
||||
using var frame = SyntheticImages.ToRgb(plane, Size, Size);
|
||||
var data = frame.Data;
|
||||
for (var i = 0; i < data.Length; i++) data[i] += 0.01f * (float)(random.NextDouble() - 0.5);
|
||||
if (k == 3)
|
||||
{
|
||||
// An aircraft light streak crossing one frame.
|
||||
for (var c = 0; c < 3; c++)
|
||||
for (var x = 10; x < 80; x++)
|
||||
frame[c, x, 40 + x / 8] = 5f;
|
||||
}
|
||||
stacker.Push(frame);
|
||||
}
|
||||
Assert.True(stacker.IsFull);
|
||||
using var output = new ImageBuffer(Size, Size);
|
||||
stacker.Render(output);
|
||||
using var reference = SyntheticImages.ToRgb(plane, Size, Size);
|
||||
double maxError = 0;
|
||||
for (var i = 0; i < output.Data.Length; i++) maxError = double.Max(maxError, double.Abs(output.Data[i] - reference.Data[i]));
|
||||
_context.Log($"max deviation from the clean frame {maxError:F4}");
|
||||
Assert.Less(maxError, 0.01);
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[Case(1)]
|
||||
[Case(5)]
|
||||
[Case(6)]
|
||||
[Case(32)]
|
||||
[Case(33)]
|
||||
public void MedianIsExact(int count)
|
||||
{
|
||||
var random = new Random(count);
|
||||
var frames = new List<ImageBuffer>();
|
||||
try
|
||||
{
|
||||
for (var k = 0; k < count; k++)
|
||||
{
|
||||
var frame = new ImageBuffer(37, 5, 3);
|
||||
var data = frame.Data;
|
||||
for (var i = 0; i < data.Length; i++) data[i] = (float)random.NextDouble();
|
||||
frames.Add(frame);
|
||||
}
|
||||
using var output = new ImageBuffer(37, 5, 3);
|
||||
TemporalStacker.Median(frames, output);
|
||||
for (var i = 0; i < output.Data.Length; i++)
|
||||
{
|
||||
var sorted = frames.Select(f => f.Data[i]).Order().ToArray();
|
||||
var expected = count % 2 == 1 ? sorted[count / 2] : 0.5f * (sorted[count / 2 - 1] + sorted[count / 2]);
|
||||
Assert.Equal(expected, output.Data[i]);
|
||||
}
|
||||
}
|
||||
finally
|
||||
{
|
||||
foreach (var f in frames) f.Dispose();
|
||||
}
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void MeanReducesNoiseBySquareRootOfN()
|
||||
{
|
||||
const int n = 16;
|
||||
const double sigma = 0.05;
|
||||
var random = new Random(3);
|
||||
using var stacker = new TemporalStacker(n, StackMode.Mean);
|
||||
using var frame = new ImageBuffer(Size, Size, 1);
|
||||
for (var k = 0; k < n; k++)
|
||||
{
|
||||
var data = frame.Data;
|
||||
for (var i = 0; i < data.Length; i++) data[i] = 0.4f + (float)(sigma * Gaussian(random));
|
||||
stacker.Push(frame);
|
||||
}
|
||||
using var output = new ImageBuffer(Size, Size, 1);
|
||||
stacker.Render(output);
|
||||
var values = output.Data.ToArray();
|
||||
var mean = values.Average(v => (double)v);
|
||||
var std = double.Sqrt(values.Average(v => (v - mean) * (v - mean)));
|
||||
_context.Log($"residual σ {std:F5} (expected {sigma / double.Sqrt(n):F5})");
|
||||
Assert.Approximately(0.4, mean, 0.002);
|
||||
Assert.Approximately(sigma / double.Sqrt(n), std, 0.15 * sigma / double.Sqrt(n));
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void WindowSlidesOverTheNewestFrames()
|
||||
{
|
||||
using var stacker = new TemporalStacker(3, StackMode.Median);
|
||||
using var frame = new ImageBuffer(4, 4, 1);
|
||||
for (var k = 0; k < 10; k++)
|
||||
{
|
||||
frame.Data.Fill(k);
|
||||
stacker.Push(frame);
|
||||
}
|
||||
Assert.Equal(3, stacker.Count);
|
||||
using var output = new ImageBuffer(4, 4, 1);
|
||||
stacker.Render(output);
|
||||
Assert.True(output.Data.ToArray().All(v => v == 8f));
|
||||
using var other = new ImageBuffer(5, 4, 1);
|
||||
Assert.Throws<ArgumentException>(() => stacker.Push(other));
|
||||
stacker.Clear();
|
||||
Assert.Throws<InvalidOperationException>(() => stacker.Render(output));
|
||||
}
|
||||
|
||||
private static int StarX(int k) => 20 + k;
|
||||
|
||||
private static int StarY(int k) => 30 + k / 3;
|
||||
|
||||
/// <summary>Dark noisy sky with one star drifting one pixel per frame and a few twinkling faint ones.</summary>
|
||||
private static void NightFrame(ImageBuffer frame, Random random, int k)
|
||||
{
|
||||
var data = frame.Data;
|
||||
for (var i = 0; i < data.Length; i++) data[i] = 0.002f + 0.001f * (float)random.NextDouble();
|
||||
for (var c = 0; c < 3; c++)
|
||||
{
|
||||
frame[c, StarX(k), StarY(k)] = 0.9f;
|
||||
frame[c, 60, 70] = 0.1f + 0.05f * (k % 3);
|
||||
}
|
||||
}
|
||||
|
||||
private static double Gaussian(Random random)
|
||||
{
|
||||
var u1 = 1.0 - random.NextDouble();
|
||||
var u2 = random.NextDouble();
|
||||
return double.Sqrt(-2 * double.Log(u1)) * double.Cos(2 * double.Pi * u2);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,123 @@
|
||||
using Titano.Core.Imaging.Geometry;
|
||||
using Titano.Core.Motion;
|
||||
using Titano.Testing;
|
||||
|
||||
namespace Titano.Core.Tests.Motion;
|
||||
|
||||
public sealed class VirtualCameraTests
|
||||
{
|
||||
private static readonly CameraKeyframe[] Path =
|
||||
[
|
||||
new(0, 0.5, 0.5, 1.0, 0),
|
||||
new(30, 0.3, 0.6, 2.0, 5),
|
||||
new(75, 0.7, 0.4, 1.5, -3),
|
||||
new(100, 0.55, 0.45, 3.0, 0) { Easing = BezierEasing.Linear },
|
||||
];
|
||||
|
||||
[Test]
|
||||
public void EasedPathHitsKeyframesExactly()
|
||||
{
|
||||
var camera = new VirtualCamera(Path.Reverse());
|
||||
foreach (var k in Path) Assert.Equal(k.State, camera.Evaluate(k.Frame));
|
||||
Assert.Equal(Path[0].State, camera.Evaluate(-10));
|
||||
Assert.Equal(Path[^1].State, camera.Evaluate(250));
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void EaseInOutPathIsC1Continuous()
|
||||
{
|
||||
var camera = new VirtualCamera(Path);
|
||||
const double h = 1e-5;
|
||||
foreach (var frame in new[] { 30.0, 75.0 })
|
||||
{
|
||||
foreach (var component in Components)
|
||||
{
|
||||
var at = component(camera.Evaluate(frame));
|
||||
var left = (at - component(camera.Evaluate(frame - h))) / h;
|
||||
var right = (component(camera.Evaluate(frame + h)) - at) / h;
|
||||
Assert.Approximately(left, right, 1e-3);
|
||||
Assert.Approximately(0, right, 1e-3);
|
||||
}
|
||||
}
|
||||
|
||||
// No jumps in velocity anywhere: neighbouring derivatives differ only by curvature × step.
|
||||
foreach (var component in Components)
|
||||
{
|
||||
double? previous = null;
|
||||
for (var t = 0.0; t <= 100; t += 0.05)
|
||||
{
|
||||
var d = (component(camera.Evaluate(t + h)) - component(camera.Evaluate(t - h))) / (2 * h);
|
||||
if (previous is { } p) Assert.Less(double.Abs(d - p), 2e-3);
|
||||
previous = d;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void EasingPresetsBehave()
|
||||
{
|
||||
for (var t = 0.0; t <= 1.0; t += 0.01)
|
||||
{
|
||||
Assert.Approximately(t, BezierEasing.Linear.Evaluate(t), 1e-9);
|
||||
Assert.Approximately(1, BezierEasing.EaseInOut.Evaluate(t) + BezierEasing.EaseInOut.Evaluate(1 - t), 1e-9);
|
||||
}
|
||||
Assert.Less(BezierEasing.EaseIn.Evaluate(0.5), 0.5);
|
||||
Assert.Greater(BezierEasing.EaseOut.Evaluate(0.5), 0.5);
|
||||
Assert.Equal(0.0, BezierEasing.EaseInOut.Evaluate(0));
|
||||
Assert.Equal(1.0, BezierEasing.EaseInOut.Evaluate(1));
|
||||
Assert.Monotonic(Enumerable.Range(0, 101).Select(i => BezierEasing.EaseInOut.Evaluate(i / 100.0)));
|
||||
// CSS "ease" reference value: cubic-bezier(0.25, 0.1, 0.25, 1) at t = 0.5 ≈ 0.8024.
|
||||
Assert.Approximately(0.8024, new BezierEasing(0.25, 0.1, 0.25, 1).Evaluate(0.5), 1e-3);
|
||||
var overshoot = new BezierEasing(0.3, 0, 0.6, 1.6);
|
||||
Assert.Greater(Enumerable.Range(0, 101).Max(i => overshoot.Evaluate(i / 100.0)), 1.0);
|
||||
Assert.Throws<ArgumentOutOfRangeException>(() => _ = new BezierEasing(1.2, 0, 0.5, 1));
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void ZoomInterpolatesGeometrically()
|
||||
{
|
||||
var camera = new VirtualCamera([new CameraKeyframe(0, 0.5, 0.5, 1, 0) { Easing = BezierEasing.Linear }, new CameraKeyframe(10, 0.5, 0.5, 4, 0)]);
|
||||
Assert.Approximately(2, camera.Evaluate(5).Zoom, 1e-12);
|
||||
Assert.Throws<ArgumentOutOfRangeException>(() => new VirtualCamera([new CameraKeyframe(0, 0.5, 0.5, 0.5, 0)]));
|
||||
Assert.Throws<ArgumentException>(() => new VirtualCamera([new CameraKeyframe(3, 0.5, 0.5, 1, 0), new CameraKeyframe(3, 0.2, 0.5, 1, 0)]));
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void ViewMapsToSourceWindow()
|
||||
{
|
||||
const int w = 1920, h = 1080;
|
||||
Assert.True(VirtualCamera.ViewToSource(new CameraState(0.5, 0.5, 1, 0), w, h).IsIdentity(1e-12));
|
||||
|
||||
var zoomed = VirtualCamera.ViewToSource(new CameraState(0.25, 0.5, 2, 0), w, h);
|
||||
var (cx, cy) = zoomed.Apply((w - 1) / 2.0, (h - 1) / 2.0);
|
||||
Assert.Within(479.5, 539.5, cx, cy, 1e-9);
|
||||
// The view's left edge lands half a view-width (w/4 source pixels) left of the centre.
|
||||
var (lx, _) = zoomed.Apply(-0.5, (h - 1) / 2.0);
|
||||
Assert.Approximately(480 - w / 4.0 - 0.5, lx, 1e-9);
|
||||
|
||||
var rolled = VirtualCamera.ViewToSource(new CameraState(0.5, 0.5, 1, 90), w, h);
|
||||
var (vx, vy) = rolled.ApplyVector(1, 0);
|
||||
Assert.Within(0, 1, vx, vy, 1e-12);
|
||||
}
|
||||
|
||||
[Test]
|
||||
public void ComposesWithStabilisationIntoOneAffine()
|
||||
{
|
||||
const int w = 640, h = 480;
|
||||
var camera = new VirtualCamera(Path);
|
||||
var correction = Affine2D.About(Affine2D.Similarity(1.01, 0.004, 1.5, -2.25), (w - 1) / 2.0, (h - 1) / 2.0);
|
||||
var combined = camera.ToSource(42.5, w, h, correction);
|
||||
var view = VirtualCamera.ViewToSource(camera.Evaluate(42.5), w, h);
|
||||
foreach (var (x, y) in new[] { (0.0, 0.0), (320.0, 240.0), (639.0, 100.0) })
|
||||
{
|
||||
// Stabilised coordinates of the source sample must be where the view looks.
|
||||
var (sx, sy) = combined.Apply(x, y);
|
||||
var (tx, ty) = correction.Apply(sx, sy);
|
||||
var (ex, ey) = view.Apply(x, y);
|
||||
Assert.Within(ex, ey, tx, ty, 1e-9);
|
||||
}
|
||||
Assert.Equal(view, camera.ToSource(42.5, w, h));
|
||||
}
|
||||
|
||||
private static readonly Func<CameraState, double>[] Components = [s => s.CenterX, s => s.CenterY, s => s.Zoom, s => s.Rotation / 100];
|
||||
}
|
||||
Reference in new issue
Block a user