From 749eafeebd7d3d33c84e644fd5317e7cf8078e43 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 09:36:42 +0000 Subject: [PATCH] =?UTF-8?q?feat(motion):=20add=20B=C3=A9zier-eased=20virtu?= =?UTF-8?q?al=20camera=20composed=20with=20stabilisation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC --- src/Titano.Core/Motion/BezierEasing.cs | 84 ++++++++++++ src/Titano.Core/Motion/VirtualCamera.cs | 87 +++++++++++++ .../Motion/VirtualCameraTests.cs | 123 ++++++++++++++++++ 3 files changed, 294 insertions(+) create mode 100644 src/Titano.Core/Motion/BezierEasing.cs create mode 100644 src/Titano.Core/Motion/VirtualCamera.cs create mode 100644 tests/Titano.Core.Tests/Motion/VirtualCameraTests.cs diff --git a/src/Titano.Core/Motion/BezierEasing.cs b/src/Titano.Core/Motion/BezierEasing.cs new file mode 100644 index 00000000..c9957084 --- /dev/null +++ b/src/Titano.Core/Motion/BezierEasing.cs @@ -0,0 +1,84 @@ +namespace Titano.Core.Motion; + +/// +/// Cubic Bézier timing curve from (0, 0) to (1, 1) with control points (X1, Y1) and (X2, Y2), as in CSS +/// cubic-bezier(). X1 and X2 must lie in [0, 1] so time is monotonic; Y values may overshoot. +/// +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); + + /// Starts at rest, arrives at speed. + public static BezierEasing EaseIn { get; } = new(0.42, 0, 1, 1); + + /// Starts at speed, arrives at rest. + public static BezierEasing EaseOut { get; } = new(0, 0, 0.58, 1); + + /// At rest at both ends: chains of these segments are C1-continuous. + public static BezierEasing EaseInOut { get; } = new(0.42, 0, 0.58, 1); + + /// Eased progress y for time fraction t ∈ [0, 1] (exactly 0 and 1 at the ends). + public double Evaluate(double t) + { + if (t <= 0) return 0; + if (t >= 1) return 1; + return Polynomial(Y1, Y2, Parameter(t)); + } + + /// Curve parameter s with x(s) = t: Newton's method from s = t, bisection when it stalls. + 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; + } + + /// B(s) = 3(1−s)²s·p1 + 3(1−s)s²·p2 + s³ in Horner form. + 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; + } +} diff --git a/src/Titano.Core/Motion/VirtualCamera.cs b/src/Titano.Core/Motion/VirtualCamera.cs new file mode 100644 index 00000000..00b14553 --- /dev/null +++ b/src/Titano.Core/Motion/VirtualCamera.cs @@ -0,0 +1,87 @@ +using Titano.Core.Imaging.Geometry; + +namespace Titano.Core.Motion; + +/// +/// 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). +/// +public readonly record struct CameraState(double CenterX, double CenterY, double Zoom, double Rotation); + +/// A virtual camera keyframe; shapes the segment from this keyframe to the next. +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); +} + +/// +/// 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. +/// +public sealed class VirtualCamera +{ + private readonly CameraKeyframe[] _keyframes; + + public VirtualCamera(IEnumerable 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 Keyframes => _keyframes; + + /// Pose at a (possibly fractional) output frame; held constant before the first and after the last keyframe. + 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); + } + + /// + /// Maps view pixel-centre coordinates (a frame-sized view) to source pixel-centre coordinates: + /// x_src = C + R(roll)·(x_view − view centre) / zoom. + /// + 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); + } + + /// + /// 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 + /// . + /// + 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; + } +} diff --git a/tests/Titano.Core.Tests/Motion/VirtualCameraTests.cs b/tests/Titano.Core.Tests/Motion/VirtualCameraTests.cs new file mode 100644 index 00000000..2bf2c91f --- /dev/null +++ b/tests/Titano.Core.Tests/Motion/VirtualCameraTests.cs @@ -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(() => _ = 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(() => new VirtualCamera([new CameraKeyframe(0, 0.5, 0.5, 0.5, 0)])); + Assert.Throws(() => 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[] Components = [s => s.CenterX, s => s.CenterY, s => s.Zoom, s => s.Rotation / 100]; +}