feat(motion): add gather-filter motion blur with shutter-angle composition

ShutterAngle computes the real angle from exposure and interval and the
blur fraction sqrt(target^2 - real^2)/360 (zero once the real angle
reaches the target). MotionBlurRenderer averages bilinear taps along
each pixel's motion vector with a tap count adaptive to the length.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-02 09:30:30 +00:00
1 parent 25c71ac97c
commit e3d3e3c729
2 files changed
+248

No files matched your search

@@ -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,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<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);
}
}
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<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);
}