viewport_lib/camera/
track.rs

1//! Keyframe camera animation with Catmull-Rom interpolation.
2
3use crate::camera::camera::{Camera, CameraTarget};
4
5// ---------------------------------------------------------------------------
6// CameraTrack
7// ---------------------------------------------------------------------------
8
9/// A time-sorted sequence of camera keyframes for animation.
10///
11/// Build the track with [`push`](Self::push), then call
12/// [`interpolate_camera`] each frame to get a smoothly interpolated
13/// [`CameraTarget`] that you can apply to a [`Camera`].
14///
15/// Center and distance are interpolated with a Catmull-Rom spline.
16/// Orientation is interpolated with spherical linear interpolation (slerp)
17/// between adjacent keyframes.
18#[derive(Clone, Debug, Default)]
19pub struct CameraTrack {
20    /// Time-sorted keyframes: `(time_seconds, target)`.
21    keyframes: Vec<(f64, CameraTarget)>,
22}
23
24impl CameraTrack {
25    /// Create an empty track.
26    pub fn new() -> Self {
27        Self::default()
28    }
29
30    /// Create a track from a pre-built list of `(time, target)` pairs.
31    ///
32    /// The list is sorted by time; duplicate times are kept (the later one wins
33    /// during interpolation).
34    pub fn from_keyframes(mut keyframes: Vec<(f64, CameraTarget)>) -> Self {
35        keyframes.sort_by(|a, b| a.0.partial_cmp(&b.0).unwrap_or(std::cmp::Ordering::Equal));
36        Self { keyframes }
37    }
38
39    /// Append a keyframe at `time` seconds, keeping the list sorted.
40    pub fn push(&mut self, time: f64, target: CameraTarget) {
41        let pos = self.keyframes.partition_point(|(t, _)| *t <= time);
42        self.keyframes.insert(pos, (time, target));
43    }
44
45    /// Return a slice of all keyframes in time order.
46    pub fn keyframes(&self) -> &[(f64, CameraTarget)] {
47        &self.keyframes
48    }
49
50    /// Duration from the first to the last keyframe, or `0.0` if empty.
51    pub fn duration(&self) -> f64 {
52        match (self.keyframes.first(), self.keyframes.last()) {
53            (Some(first), Some(last)) => (last.0 - first.0).max(0.0),
54            _ => 0.0,
55        }
56    }
57
58    /// Return `true` if the track has no keyframes.
59    pub fn is_empty(&self) -> bool {
60        self.keyframes.is_empty()
61    }
62
63    /// Number of keyframes.
64    pub fn len(&self) -> usize {
65        self.keyframes.len()
66    }
67}
68
69// ---------------------------------------------------------------------------
70// Interpolation
71// ---------------------------------------------------------------------------
72
73/// Interpolate a [`CameraTarget`] from a [`CameraTrack`] at time `t`.
74///
75/// - Center and distance use Catmull-Rom spline interpolation.
76/// - Orientation uses spherical linear interpolation between the two
77///   surrounding keyframes.
78///
79/// If the track is empty a default `CameraTarget` is returned. If `t` is
80/// before the first keyframe, the first keyframe is returned; if after the
81/// last, the last keyframe is returned.
82pub fn interpolate_camera(track: &CameraTrack, t: f64) -> CameraTarget {
83    let kfs = track.keyframes();
84
85    match kfs.len() {
86        0 => CameraTarget {
87            center: glam::Vec3::ZERO,
88            distance: 5.0,
89            orientation: glam::Quat::IDENTITY,
90        },
91        1 => kfs[0].1,
92        _ => {
93            // Clamp to track range.
94            if t <= kfs[0].0 {
95                return kfs[0].1;
96            }
97            if t >= kfs[kfs.len() - 1].0 {
98                return kfs[kfs.len() - 1].1;
99            }
100
101            // Find segment index i such that kfs[i].time <= t < kfs[i+1].time.
102            let i = kfs.partition_point(|(kt, _)| *kt <= t).saturating_sub(1);
103            let i = i.min(kfs.len() - 2);
104
105            let t0 = kfs[i].0;
106            let t1 = kfs[i + 1].0;
107            let s = if (t1 - t0).abs() < 1e-12 {
108                0.0_f32
109            } else {
110                ((t - t0) / (t1 - t0)) as f32
111            };
112
113            // Gather 4 control points (with phantom endpoints at boundaries).
114            let p1 = kfs[i].1;
115            let p2 = kfs[i + 1].1;
116            let p0 = if i > 0 {
117                kfs[i - 1].1
118            } else {
119                // Phantom: reflect p2 through p1.
120                CameraTarget {
121                    center: p1.center * 2.0 - p2.center,
122                    distance: p1.distance * 2.0 - p2.distance,
123                    orientation: p1.orientation, // kept simple for boundary
124                }
125            };
126            let p3 = if i + 2 < kfs.len() {
127                kfs[i + 2].1
128            } else {
129                // Phantom: reflect p1 through p2.
130                CameraTarget {
131                    center: p2.center * 2.0 - p1.center,
132                    distance: p2.distance * 2.0 - p1.distance,
133                    orientation: p2.orientation,
134                }
135            };
136
137            CameraTarget {
138                center: catmull_rom_vec3(p0.center, p1.center, p2.center, p3.center, s),
139                distance: catmull_rom_f32(p0.distance, p1.distance, p2.distance, p3.distance, s)
140                    .max(Camera::MIN_DISTANCE),
141                orientation: p1.orientation.slerp(p2.orientation, s).normalize(),
142            }
143        }
144    }
145}
146
147// ---------------------------------------------------------------------------
148// Helpers
149// ---------------------------------------------------------------------------
150
151fn catmull_rom_f32(p0: f32, p1: f32, p2: f32, p3: f32, s: f32) -> f32 {
152    let s2 = s * s;
153    let s3 = s2 * s;
154    0.5 * (2.0 * p1
155        + (-p0 + p2) * s
156        + (2.0 * p0 - 5.0 * p1 + 4.0 * p2 - p3) * s2
157        + (-p0 + 3.0 * p1 - 3.0 * p2 + p3) * s3)
158}
159
160fn catmull_rom_vec3(
161    p0: glam::Vec3,
162    p1: glam::Vec3,
163    p2: glam::Vec3,
164    p3: glam::Vec3,
165    s: f32,
166) -> glam::Vec3 {
167    glam::Vec3::new(
168        catmull_rom_f32(p0.x, p1.x, p2.x, p3.x, s),
169        catmull_rom_f32(p0.y, p1.y, p2.y, p3.y, s),
170        catmull_rom_f32(p0.z, p1.z, p2.z, p3.z, s),
171    )
172}
173
174// ---------------------------------------------------------------------------
175// Tests
176// ---------------------------------------------------------------------------
177
178#[cfg(test)]
179mod tests {
180    use super::*;
181
182    fn target(x: f32, d: f32) -> CameraTarget {
183        CameraTarget {
184            center: glam::Vec3::new(x, 0.0, 0.0),
185            distance: d,
186            orientation: glam::Quat::IDENTITY,
187        }
188    }
189
190    #[test]
191    fn test_empty_track_returns_default() {
192        let track = CameraTrack::new();
193        let t = interpolate_camera(&track, 0.0);
194        assert_eq!(t.distance, 5.0);
195    }
196
197    #[test]
198    fn test_single_keyframe() {
199        let mut track = CameraTrack::new();
200        track.push(0.0, target(3.0, 7.0));
201        let t = interpolate_camera(&track, 5.0);
202        assert!((t.center.x - 3.0).abs() < 1e-5);
203        assert!((t.distance - 7.0).abs() < 1e-5);
204    }
205
206    #[test]
207    fn test_clamp_before_start() {
208        let mut track = CameraTrack::new();
209        track.push(1.0, target(1.0, 1.0));
210        track.push(2.0, target(2.0, 2.0));
211        let t = interpolate_camera(&track, 0.0);
212        assert!((t.center.x - 1.0).abs() < 1e-5);
213    }
214
215    #[test]
216    fn test_clamp_after_end() {
217        let mut track = CameraTrack::new();
218        track.push(1.0, target(1.0, 1.0));
219        track.push(2.0, target(2.0, 2.0));
220        let t = interpolate_camera(&track, 5.0);
221        assert!((t.center.x - 2.0).abs() < 1e-5);
222    }
223
224    #[test]
225    fn test_midpoint_two_keyframes() {
226        let mut track = CameraTrack::new();
227        track.push(0.0, target(0.0, 4.0));
228        track.push(1.0, target(2.0, 8.0));
229        // At exactly t=0.5, Catmull-Rom with phantom endpoints on a linear
230        // sequence should give the midpoint.
231        let t = interpolate_camera(&track, 0.5);
232        assert!((t.center.x - 1.0).abs() < 0.05, "center.x={}", t.center.x);
233        assert!((t.distance - 6.0).abs() < 0.1, "distance={}", t.distance);
234    }
235
236    #[test]
237    fn test_keyframe_hit_exact() {
238        let mut track = CameraTrack::new();
239        track.push(0.0, target(0.0, 1.0));
240        track.push(1.0, target(5.0, 3.0));
241        track.push(2.0, target(10.0, 5.0));
242        // At t=1.0 exactly we should be at the second keyframe.
243        let t = interpolate_camera(&track, 1.0);
244        assert!((t.center.x - 5.0).abs() < 1e-4, "center.x={}", t.center.x);
245        assert!((t.distance - 3.0).abs() < 1e-4, "distance={}", t.distance);
246    }
247
248    #[test]
249    fn test_from_keyframes_sorts() {
250        let kfs = vec![
251            (2.0_f64, target(2.0, 2.0)),
252            (0.0_f64, target(0.0, 0.0)),
253            (1.0_f64, target(1.0, 1.0)),
254        ];
255        let track = CameraTrack::from_keyframes(kfs);
256        assert_eq!(track.keyframes()[0].0, 0.0);
257        assert_eq!(track.keyframes()[1].0, 1.0);
258        assert_eq!(track.keyframes()[2].0, 2.0);
259    }
260
261    #[test]
262    fn test_duration() {
263        let mut track = CameraTrack::new();
264        assert_eq!(track.duration(), 0.0);
265        track.push(1.0, target(0.0, 1.0));
266        track.push(4.0, target(1.0, 2.0));
267        assert!((track.duration() - 3.0).abs() < 1e-10);
268    }
269
270    #[test]
271    fn test_push_keeps_sorted() {
272        let mut track = CameraTrack::new();
273        track.push(3.0, target(3.0, 3.0));
274        track.push(1.0, target(1.0, 1.0));
275        track.push(2.0, target(2.0, 2.0));
276        assert_eq!(track.keyframes()[0].0, 1.0);
277        assert_eq!(track.keyframes()[1].0, 2.0);
278        assert_eq!(track.keyframes()[2].0, 3.0);
279    }
280}
viewport_lib/camera/track.rs

viewport_lib/camera/
track.rs
