Per frame, nine phase-correlation patches on a 3x3 grid are gated by noise-compensated gradient energy (Immerkær noise estimate) and peak sharpness, then fitted with a similarity by exhaustive two-point hypotheses and weighted least squares on the inliers. Solve smooths the camera path with Gaussian-weighted local linear regression, derives corrections, shake RMS, recommendation (> 0.3 px) and the crop needed to hide borders. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
172 lines
7.2 KiB
C#
172 lines
7.2 KiB
C#
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);
|
|
}
|
|
}
|