feat(motion): add Bézier-eased virtual camera composed with stabilisation
BezierEasing evaluates CSS-style cubic-bezier timing curves (Newton with bisection fallback) with linear, ease-in, ease-out and ease-in-out presets. VirtualCamera interpolates centre, roll and geometric zoom between keyframes and returns one view-to-source affine composed with the inverse stabiliser correction. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
3 files changed
+294
No files matched your search
@@ -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,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,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