diff --git a/src/Titano.Core/Motion/MotionBlurRenderer.cs b/src/Titano.Core/Motion/MotionBlurRenderer.cs new file mode 100644 index 00000000..af4f9bf2 --- /dev/null +++ b/src/Titano.Core/Motion/MotionBlurRenderer.cs @@ -0,0 +1,143 @@ +using Titano.Core.Imaging; + +namespace Titano.Core.Motion; + +/// Shutter-angle arithmetic for synthetic motion blur. +public static class ShutterAngle +{ + /// Shutter angle actually used by the camera, 360° × exposure / interval. + public static double FromExposure(double exposureSeconds, double intervalSeconds) + { + ArgumentOutOfRangeException.ThrowIfNegative(exposureSeconds); + ArgumentOutOfRangeException.ThrowIfNegativeOrZero(intervalSeconds); + return 360.0 * exposureSeconds / intervalSeconds; + } + + /// + /// 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). + /// + 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; + } +} + +/// Tuning for . +public sealed record MotionBlurOptions +{ + /// Samples per pixel of blur length (≥ 1 keeps the bilinear taps overlapping). + public double TapsPerPixel { get; init; } = 1.0; + + /// Upper bound on samples per pixel. + public int MaxTaps { get; init; } = 64; +} + +/// +/// 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. +/// +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; } + + /// + /// Renders blurred along (frame-to-frame vectors) + /// scaled by (see ). + /// + 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 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); + } + } +} diff --git a/tests/Titano.Core.Tests/Motion/MotionBlurTests.cs b/tests/Titano.Core.Tests/Motion/MotionBlurTests.cs new file mode 100644 index 00000000..96c94d7e --- /dev/null +++ b/tests/Titano.Core.Tests/Motion/MotionBlurTests.cs @@ -0,0 +1,105 @@ +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; + + [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(); + 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); + } + } + 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); + Assert.Approximately(before, after, 2e-3 * before); + } + Assert.False(source.Data.SequenceEqual(output.Data)); + } + + private static double Mean(ReadOnlySpan 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); +}