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:
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);
|
||||
}
|
||||
Reference in new issue
Block a user