Skip to main content

alpha2_eval/
data.rs

1//! Reads data sets at render time for the `data` value mode and picture corrections.
2//!
3//! A source-anchored set is read at the source time its reader shows (a clip's picture time
4//! map, or a media node's start plus composition time), so a bound value follows the picture
5//! through any time map.
6
7use alpha2_model::{
8    Clip, ClipId, DataAnchor, DataBinding, DataInterpolation, DataKind, DataSamples, DataSet,
9    DataSetId, DataSpace, DataValues, DataVia, NodeId, Project, Vec2,
10};
11use alpha2_time::MediaTime;
12use std::collections::HashMap;
13
14/// Data sets and clips by id, with each set's displayed picture size.
15#[derive(Clone, Debug, Default)]
16pub struct DataIndex {
17    sets: HashMap<DataSetId, usize>,
18    clips: HashMap<ClipId, (usize, usize)>,
19    /// Per set, its source picture's displayed size from `made_from`, else the source fingerprint.
20    picture_sizes: Vec<Option<(u32, u32)>>,
21}
22
23impl DataIndex {
24    /// Indexes `project`'s data sets and clips. Empty when the project has no data.
25    #[must_use]
26    pub fn new(project: &Project) -> Self {
27        if project.data.is_empty() {
28            return Self::default();
29        }
30        let sources = project
31            .sources
32            .iter()
33            .map(|source| (&source.id, source))
34            .collect::<HashMap<_, _>>();
35        let video_size = |fingerprint: Option<&alpha2_model::MediaFingerprint>| {
36            fingerprint
37                .and_then(|fingerprint| fingerprint.streams.as_ref())
38                .and_then(|streams| streams.video.as_ref())
39                .filter(|video| video.width > 0 && video.height > 0)
40                .map(|video| (video.width, video.height))
41        };
42        Self {
43            sets: project
44                .data
45                .iter()
46                .enumerate()
47                .map(|(index, set)| (set.id.clone(), index))
48                .collect(),
49            clips: project
50                .timeline
51                .tracks
52                .iter()
53                .enumerate()
54                .flat_map(|(track, entry)| {
55                    entry
56                        .clips
57                        .iter()
58                        .enumerate()
59                        .map(move |(clip, value)| (value.id.clone(), (track, clip)))
60                })
61                .collect(),
62            picture_sizes: project
63                .data
64                .iter()
65                .map(|set| {
66                    video_size(set.made_from.as_ref()).or_else(|| {
67                        set.anchor
68                            .source()
69                            .and_then(|source| sources.get(source))
70                            .and_then(|source| video_size(source.fingerprint.as_ref()))
71                    })
72                })
73                .collect(),
74        }
75    }
76
77    fn set<'p>(&self, project: &'p Project, id: &DataSetId) -> Option<(&'p DataSet, usize)> {
78        let index = *self.sets.get(id)?;
79        project.data.get(index).map(|set| (set, index))
80    }
81
82    fn clip<'p>(&self, project: &'p Project, id: &ClipId) -> Option<&'p Clip> {
83        let (track, clip) = *self.clips.get(id)?;
84        project.timeline.tracks.get(track)?.clips.get(clip)
85    }
86}
87
88/// What a sampled value reads data through, the project's data sets and the clock of its place.
89#[derive(Clone, Copy)]
90pub struct SampleContext<'a> {
91    scope: Option<Scope<'a>>,
92}
93
94#[derive(Clone, Copy)]
95struct Scope<'a> {
96    project: &'a Project,
97    index: &'a DataIndex,
98    nodes: Option<Nodes<'a>>,
99}
100
101/// Where a composition-time value finds the `media` node it reads through.
102#[derive(Clone, Copy)]
103enum Nodes<'a> {
104    /// A step of a compiled plan, whose inlined path names the node's siblings.
105    Step(&'a crate::CompositionPlan, usize),
106    /// A composition's own nodes.
107    Composition(&'a alpha2_model::Composition),
108}
109
110impl Nodes<'_> {
111    fn media_start(&self, via: &NodeId) -> Option<MediaTime> {
112        match self {
113            Self::Step(plan, step) => plan.media_start(*step, via),
114            Self::Composition(composition) => {
115                composition.nodes.iter().find_map(|node| match &node.op {
116                    alpha2_model::NodeOp::Media { start, .. } if &node.id == via => Some(*start),
117                    _ => None,
118                })
119            }
120        }
121    }
122
123    fn same(&self, other: &Self) -> bool {
124        match (self, other) {
125            (Self::Step(a, i), Self::Step(b, j)) => std::ptr::eq(*a, *b) && i == j,
126            (Self::Composition(a), Self::Composition(b)) => std::ptr::eq(*a, *b),
127            _ => false,
128        }
129    }
130}
131
132/// Two contexts are equal when they read the same project, index and node starts.
133impl PartialEq for SampleContext<'_> {
134    fn eq(&self, other: &Self) -> bool {
135        match (&self.scope, &other.scope) {
136            (None, None) => true,
137            (Some(left), Some(right)) => {
138                std::ptr::eq(left.project, right.project)
139                    && std::ptr::eq(left.index, right.index)
140                    && match (left.nodes, right.nodes) {
141                        (None, None) => true,
142                        (Some(a), Some(b)) => a.same(&b),
143                        _ => false,
144                    }
145            }
146            _ => false,
147        }
148    }
149}
150
151impl std::fmt::Debug for SampleContext<'_> {
152    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
153        formatter
154            .debug_struct("SampleContext")
155            .field("data", &self.scope.is_some())
156            .finish()
157    }
158}
159
160impl<'a> SampleContext<'a> {
161    /// No data, so a bound value evaluates as having no samples.
162    pub const NONE: SampleContext<'static> = SampleContext { scope: None };
163
164    /// Timeline-time places of `project`.
165    #[must_use]
166    pub const fn timeline(project: &'a Project, index: &'a DataIndex) -> Self {
167        Self {
168            scope: Some(Scope {
169                project,
170                index,
171                nodes: None,
172            }),
173        }
174    }
175
176    /// Composition-time places of `composition`, read through its own `media` nodes.
177    #[must_use]
178    pub const fn composition(
179        project: &'a Project,
180        index: &'a DataIndex,
181        composition: &'a alpha2_model::Composition,
182    ) -> Self {
183        Self {
184            scope: Some(Scope {
185                project,
186                index,
187                nodes: Some(Nodes::Composition(composition)),
188            }),
189        }
190    }
191
192    /// The same data read at step `step` of `plan`, whose settings are in composition time and
193    /// read through the `media` steps inlined beside it.
194    #[must_use]
195    pub fn for_step(&self, plan: &'a crate::CompositionPlan, step: usize) -> Self {
196        Self {
197            scope: self.scope.map(|scope| Scope {
198                nodes: Some(Nodes::Step(plan, step)),
199                ..scope
200            }),
201        }
202    }
203
204    /// The same data read at timeline-time places.
205    #[must_use]
206    pub fn for_timeline(&self) -> Self {
207        Self {
208            scope: self.scope.map(|scope| Scope {
209                nodes: None,
210                ..scope
211            }),
212        }
213    }
214
215    /// The canvas width over height, or 1 without a project.
216    fn canvas_aspect(&self) -> f64 {
217        self.scope.map_or(1.0, |scope| {
218            f64::from(scope.project.settings.width) / f64::from(scope.project.settings.height)
219        })
220    }
221}
222
223/// A similarity of a clip's picture, sampled from a correction's data set.
224#[derive(Copy, Clone, Debug, PartialEq)]
225pub struct Correction {
226    /// Translation in fractions of the displayed picture's width and height.
227    pub translate: Vec2,
228    /// Clockwise rotation in degrees about the picture's center.
229    pub rotation_degrees: f32,
230    /// Uniform scale about the picture's center.
231    pub scale: f32,
232    /// The picture's size as a fraction of the canvas-shaped layer it is contain-fitted into.
233    pub picture: Vec2,
234}
235
236impl Correction {
237    /// Applies the correction to a point in the layer's normalized coordinates. `aspect` is the
238    /// layer's width over height; rotation and scale act in pixel space about the center.
239    #[must_use]
240    pub fn apply(&self, point: Vec2, aspect: f64) -> Vec2 {
241        let (sin, cos) = libm::sincos(f64::from(self.rotation_degrees).to_radians());
242        let scale = f64::from(self.scale);
243        let x = (f64::from(point.x) - 0.5) * aspect;
244        let y = f64::from(point.y) - 0.5;
245        let turned_x = scale * (cos * x - sin * y);
246        let turned_y = scale * (sin * x + cos * y);
247        Vec2::new(
248            finite(
249                0.5 + turned_x / aspect + f64::from(self.translate.x) * f64::from(self.picture.x),
250            ),
251            finite(0.5 + turned_y + f64::from(self.translate.y) * f64::from(self.picture.y)),
252        )
253    }
254}
255
256#[allow(clippy::cast_possible_truncation)]
257fn finite(value: f64) -> f32 {
258    if value.is_finite() {
259        value.clamp(f64::from(f32::MIN), f64::from(f32::MAX)) as f32
260    } else {
261        0.0
262    }
263}
264
265/// The displayed picture's size as a fraction of a canvas-shaped layer it is contain-fitted
266/// into, as the renderer centres it.
267#[must_use]
268pub fn contained_picture(picture: (u32, u32), canvas_aspect: f64) -> Vec2 {
269    let picture_aspect = f64::from(picture.0) / f64::from(picture.1);
270    if picture_aspect >= canvas_aspect {
271        Vec2::new(1.0, finite(canvas_aspect / picture_aspect))
272    } else {
273        Vec2::new(finite(picture_aspect / canvas_aspect), 1.0)
274    }
275}
276
277/// A point normalized to the displayed picture, in the normalized coordinates of the layer the
278/// picture is contain-fitted into.
279fn picture_to_layer(point: Vec2, picture: Vec2) -> Vec2 {
280    Vec2::new(
281        finite(0.5 + (f64::from(point.x) - 0.5) * f64::from(picture.x)),
282        finite(0.5 + (f64::from(point.y) - 0.5) * f64::from(picture.y)),
283    )
284}
285
286/// The value of `channel` at `time`, `arity` numbers, with the data rules: `hold` takes the
287/// sample at or before `time`, `linear` interpolates between two known neighbours, a lost
288/// sample holds the last known value, and times outside the samples clamp. `None` when the
289/// channel has no known value.
290#[must_use]
291pub fn sample_channel(
292    samples: &DataSamples,
293    channel: usize,
294    arity: usize,
295    time: MediaTime,
296) -> Option<Vec<f32>> {
297    let width = samples.channels.len().max(1) * arity;
298    let at = |sample: usize| -> Option<&[Option<f32>]> {
299        let start = sample * width + channel * arity;
300        samples.values.get(start..start + arity)
301    };
302    let known = |sample: usize| at(sample).filter(|values| values[0].is_some());
303    let collect =
304        |values: &[Option<f32>]| values.iter().map(|value| value.unwrap_or(0.0)).collect();
305    let next = samples.times.partition_point(|sample| *sample <= time);
306    let Some(current) = next.checked_sub(1) else {
307        // Before the first sample: the first known one.
308        return (0..samples.times.len()).find_map(known).map(collect);
309    };
310    if let Some(left) = known(current) {
311        if samples.interpolation == DataInterpolation::Linear
312            && samples.times[current] < time
313            && let Some(right) = known(next)
314        {
315            // The keyframe interpolation, so a baked binding evaluates alike.
316            let amount = crate::animation::interpolation_amount(
317                samples.times[current],
318                samples.times[next],
319                time,
320            );
321            return Some(
322                left.iter()
323                    .zip(right)
324                    .map(|(from, to)| {
325                        crate::animation::interpolate_f32(
326                            from.unwrap_or(0.0),
327                            to.unwrap_or(0.0),
328                            amount,
329                        )
330                    })
331                    .collect(),
332            );
333        }
334        return Some(collect(left));
335    }
336    // Lost here: the last known value before, else the first known one after.
337    (0..current)
338        .rev()
339        .find_map(known)
340        .or_else(|| (next..samples.times.len()).find_map(known))
341        .map(collect)
342}
343
344/// The anchor time a binding reads at when its place is sampled at `time`.
345fn anchor_time(
346    scope: &Scope<'_>,
347    set: &DataSet,
348    binding: &DataBinding,
349    time: MediaTime,
350) -> Option<MediaTime> {
351    match (&set.anchor, &binding.via) {
352        (DataAnchor::Timeline, _) => Some(time),
353        (DataAnchor::Source { .. }, Some(DataVia::Clip(clip))) => {
354            let clip = scope.index.clip(scope.project, clip)?;
355            crate::picture_source_time(
356                clip.timeline_range,
357                clip.source_range,
358                clip.time_map,
359                scope.project.settings.frame_rate,
360                time,
361            )
362        }
363        (DataAnchor::Source { .. }, Some(DataVia::Node(node))) => {
364            let start = scope.nodes?.media_start(node)?;
365            Some(MediaTime(start.ticks().saturating_add(time.ticks())))
366        }
367        (DataAnchor::Source { .. }, None) => None,
368    }
369}
370
371/// The kind of the data set `binding` follows, if it exists.
372#[must_use]
373pub fn bound_kind(binding: &DataBinding, context: &SampleContext<'_>) -> Option<DataKind> {
374    let scope = context.scope?;
375    scope
376        .index
377        .set(scope.project, &binding.data)
378        .map(|(set, _)| set.kind())
379}
380
381/// A scalar binding's value at `time`, remapped; `None` without a value.
382#[must_use]
383pub fn bound_scalar(
384    binding: &DataBinding,
385    time: MediaTime,
386    context: &SampleContext<'_>,
387) -> Option<f32> {
388    let scope = context.scope?;
389    let (set, _) = scope.index.set(scope.project, &binding.data)?;
390    let DataValues::Scalars(samples) = &set.values else {
391        return None;
392    };
393    let at = anchor_time(&scope, set, binding, time)?;
394    let value = *sample_channel(samples, samples.channel(&binding.channel)?, 1, at)?.first()?;
395    Some(binding.remap.map_or(value, |remap| remap.apply(value)))
396}
397
398/// A two-component binding's value at `time`, a point in its space plus its offset or a scalar in
399/// both components. `None` without a value.
400#[must_use]
401pub fn bound_vec2(
402    binding: &DataBinding,
403    time: MediaTime,
404    context: &SampleContext<'_>,
405) -> Option<Vec2> {
406    let scope = context.scope?;
407    let (set, index) = scope.index.set(scope.project, &binding.data)?;
408    match &set.values {
409        DataValues::Scalars(_) => {
410            bound_scalar(binding, time, context).map(|value| Vec2::new(value, value))
411        }
412        DataValues::Points(samples) => {
413            let at = anchor_time(&scope, set, binding, time)?;
414            let values = sample_channel(samples, samples.channel(&binding.channel)?, 2, at)?;
415            let point = Vec2::new(values[0], values[1]);
416            let placed = match (&set.anchor, binding.space) {
417                (DataAnchor::Timeline, _) | (_, None) => point,
418                (DataAnchor::Source { .. }, Some(space)) => {
419                    let aspect = context.canvas_aspect();
420                    let picture = scope.index.picture_sizes[index]
421                        .map_or(Vec2::new(1.0, 1.0), |size| contained_picture(size, aspect));
422                    let layer = picture_to_layer(point, picture);
423                    match (space, &binding.via) {
424                        (DataSpace::Canvas, Some(DataVia::Clip(clip))) => {
425                            let clip = scope.index.clip(scope.project, clip)?;
426                            layer_to_canvas(clip, layer, time, context)
427                        }
428                        _ => layer,
429                    }
430                }
431            };
432            let [x, y] = binding.offset.unwrap_or_default();
433            Some(Vec2::new(placed.x + x, placed.y + y))
434        }
435        DataValues::Similarity(_) | DataValues::Words(_) | DataValues::Intervals(_) => None,
436    }
437}
438
439/// A point of `clip`'s layer at `time` in normalized canvas coordinates: through its correction,
440/// then its evaluated visual, as the compositor places the layer.
441fn layer_to_canvas(clip: &Clip, layer: Vec2, time: MediaTime, context: &SampleContext<'_>) -> Vec2 {
442    let aspect = context.canvas_aspect();
443    let corrected = correction_at(clip, time, context)
444        .map_or(layer, |correction| correction.apply(layer, aspect));
445    let visual = crate::sample_visual(&clip.visual, time, aspect, context);
446    let (sin, cos) = libm::sincos(f64::from(visual.rotation_degrees).to_radians());
447    let x =
448        (f64::from(corrected.x) - f64::from(visual.anchor.x)) * f64::from(visual.scale.x) * aspect;
449    let y = (f64::from(corrected.y) - f64::from(visual.anchor.y)) * f64::from(visual.scale.y);
450    Vec2::new(
451        finite(f64::from(visual.position.x) + (cos * x - sin * y) / aspect),
452        finite(f64::from(visual.position.y) + sin * x + cos * y),
453    )
454}
455
456/// `clip`'s correction at timeline `time`, if it has one with a value there.
457#[must_use]
458pub fn correction_at(
459    clip: &Clip,
460    time: MediaTime,
461    context: &SampleContext<'_>,
462) -> Option<Correction> {
463    clip_correction(
464        &clip.visual,
465        (clip.timeline_range, clip.source_range, clip.time_map),
466        time,
467        context,
468    )
469}
470
471/// The correction `visual` names at timeline `time`, for a clip placed by `placement`
472/// (timeline range, source range, time map).
473pub(crate) fn clip_correction(
474    visual: &alpha2_model::VisualProperties,
475    placement: (
476        alpha2_time::TimeRange,
477        alpha2_time::TimeRange,
478        alpha2_model::TimeMap,
479    ),
480    time: MediaTime,
481    context: &SampleContext<'_>,
482) -> Option<Correction> {
483    let reference = visual.correction.as_ref()?;
484    let scope = context.scope?;
485    let (set, index) = scope.index.set(scope.project, &reference.data)?;
486    let DataValues::Similarity(samples) = &set.values else {
487        return None;
488    };
489    let (timeline_range, source_range, time_map) = placement;
490    let at = crate::picture_source_time(
491        timeline_range,
492        source_range,
493        time_map,
494        scope.project.settings.frame_rate,
495        time,
496    )?;
497    let values = sample_channel(samples, 0, DataKind::Similarity.arity().unwrap_or(4), at)?;
498    let picture = scope.index.picture_sizes[index].map_or(Vec2::new(1.0, 1.0), |size| {
499        contained_picture(size, context.canvas_aspect())
500    });
501    Some(Correction {
502        translate: Vec2::new(values[0], values[1]),
503        rotation_degrees: values[2],
504        scale: values[3],
505        picture,
506    })
507}
508
509/// The first tick after `after` at which a timeline-time binding can read another sample: a
510/// sample time passing under the reader's time map, or a loop pass starting. Between two such
511/// ticks a `hold` binding is constant and a `linear` one changes linearly with timeline time.
512/// `None` when the value never changes again.
513#[must_use]
514pub fn next_data_change(
515    binding: &DataBinding,
516    after: MediaTime,
517    context: &SampleContext<'_>,
518) -> Option<MediaTime> {
519    let scope = context.scope?;
520    let (set, _) = scope.index.set(scope.project, &binding.data)?;
521    let samples = set.values.samples()?;
522    let times = &samples.times;
523    match (&set.anchor, &binding.via) {
524        (DataAnchor::Timeline, _) => times
525            .get(times.partition_point(|time| *time <= after))
526            .copied(),
527        (DataAnchor::Source { .. }, Some(DataVia::Clip(clip))) => {
528            let clip = scope.index.clip(scope.project, clip)?;
529            let rate = scope.project.settings.frame_rate;
530            let (start, end) = (
531                clip.timeline_range.start().ticks(),
532                clip.timeline_range.end().ticks(),
533            );
534            if after.ticks() >= end {
535                return None;
536            }
537            if after.ticks() < start {
538                return Some(clip.timeline_range.start());
539            }
540            let shown = |tick: i64| {
541                crate::picture_source_time(
542                    clip.timeline_range,
543                    clip.source_range,
544                    clip.time_map,
545                    rate,
546                    MediaTime(tick),
547                )
548                .map_or(i64::MIN, MediaTime::ticks)
549            };
550            // The first tick past `after` whose sample index differs from the current one.
551            let index_at = |tick: i64| times.partition_point(|time| time.ticks() <= shown(tick));
552            let current = index_at(after.ticks());
553            let (mut low, mut high) = (after.ticks() + 1, end);
554            // The sample index is monotone within a stretch; a loop pass boundary is a change too.
555            if let alpha2_model::TimeMap::Loop { .. } = clip.time_map {
556                let length = clip.source_range.duration()?.ticks();
557                let pass_end = start + ((after.ticks() - start) / length + 1) * length;
558                high = high.min(pass_end);
559                if index_at(high.min(end - 1)) == current && high < end {
560                    return Some(MediaTime(high));
561                }
562            }
563            if index_at(high - 1) == current {
564                return (high < end).then_some(MediaTime(high));
565            }
566            while low < high {
567                let middle = low + (high - low) / 2;
568                if index_at(middle) == current {
569                    low = middle + 1;
570                } else {
571                    high = middle;
572                }
573            }
574            Some(MediaTime(low))
575        }
576        (DataAnchor::Source { .. }, _) => None,
577    }
578}