665bfac0b339
masks.rs
//! Layer masks: path, mode, invert, feather, opacity and expansion, with keyframes and
//! expressions, in EffectCraft's units.
//!
//! Units (`docs/aep-format.md` 3.4 and 3.8): the path is stored as `f32` points normalised inside a
//! box that is itself normalised to the **layer source** size (090 on a 1920x1080 solid, 309 on a
//! 100x100 solid), so vertices become layer pixels with the origin at the layer's top left, as the
//! project's masks are; a tangent is the handle minus the vertex (232). Feather and expansion are
//! pixels, opacity a fraction (percent here). The path keyframes (64-byte records, 093) carry time,
//! interpolation, label, roving and the ease at byte 24 (599, 700: EffectCraft's path at 0.5 / 1 /
//! 1.5 s within 0.5 px of After Effects'); only speed 0 is sampled, another speed is imported as
//! progress per second and reported.
use crate::{Layer as AepLayer, MaskAtom, MaskMode as AepMode, PropNode, ShapePath as AepPath, ValueSource};
use effectcraft_keyframe::{Interp, Keyframe, ShapePath, Value};
use effectcraft_project::build::{self, Ids};
use effectcraft_project::{GroupKind, MaskMode, Node, PropGroup as EcGroup};
use crate::import::props::{Kind, LIMIT, ease, import_expression, import_keys, interp, sort_unique};
use crate::import::report::{Collector, LossCategory};
use crate::import::time::TimeMap;
/// The most vertices one mask path may have (a traced mask has a few hundred). Larger paths are
/// reported as damaged data and the mask is not imported.
pub(crate) const MAX_VERTICES: usize = 65_536;
fn mode(m: AepMode) -> Option<MaskMode> {
Some(match m {
AepMode::None => MaskMode::None,
AepMode::Add => MaskMode::Add,
AepMode::Subtract => MaskMode::Subtract,
AepMode::Intersect => MaskMode::Intersect,
AepMode::Lighten => MaskMode::Lighten,
AepMode::Darken => MaskMode::Darken,
AepMode::Difference => MaskMode::Difference,
AepMode::Other(_) => return None,
})
}
/// A stored path in layer pixels (`size` is the layer's source size), or why it cannot be used.
/// The path of a mask whose path was never set: the source rectangle, clockwise from the top left
/// as After Effects reads it back (900: `[0,0] [0,1080] [1920,1080] [1920,0]`), no tangents.
fn source_rectangle(size: (u32, u32)) -> ShapePath {
let (w, h) = (f64::from(size.0), f64::from(size.1));
ShapePath {
vertices: vec![[0.0, 0.0], [0.0, h], [w, h], [w, 0.0]],
in_tangents: vec![[0.0, 0.0]; 4],
out_tangents: vec![[0.0, 0.0]; 4],
closed: true,
feather: Vec::new(),
}
}
/// [`to_path`]'s error for a stored path without vertices.
pub(crate) const NO_VERTICES: &str = "its path has no vertices";
pub(crate) fn to_path(s: &AepPath, size: (u32, u32)) -> Result<ShapePath, &'static str> {
if !s.points.len().is_multiple_of(3) {
return Err("its point count is not a multiple of three");
}
let n = s.vertex_count();
if n == 0 {
return Err(NO_VERTICES);
}
if n > MAX_VERTICES {
return Err("its path has too many vertices");
}
let vertices = s.vertices((f64::from(size.0), f64::from(size.1)));
let ok = |p: [f64; 2]| p.iter().all(|c| c.is_finite() && c.abs() <= LIMIT);
let mut path = ShapePath {
vertices: Vec::with_capacity(n),
in_tangents: Vec::with_capacity(n),
out_tangents: Vec::with_capacity(n),
closed: !s.open,
feather: Vec::new(),
};
for v in &vertices {
let (i, o) = (v.in_tangent(), v.out_tangent());
if !(ok(v.position) && ok(i) && ok(o)) {
return Err("its path holds a number that is not valid");
}
path.vertices.push(v.position);
path.in_tangents.push(i);
path.out_tangents.push(o);
}
Ok(path)
}
/// The layer whose masks are imported.
#[derive(Clone, Copy)]
pub(crate) struct MaskLayer<'a> {
/// The layer's source size (1 x 1 on a layer without a source, whose mask boxes are pixels).
pub size: (u32, u32),
/// Whether the layer has a source (a mask without a stored path is then its rectangle, 900).
pub source: bool,
pub tm: &'a TimeMap,
}
/// Imports the masks of `layer` into its `masks` group.
pub(crate) fn import_masks(
layer: &AepLayer<'_, '_>,
comp: &str,
layer_name: &str,
ml: MaskLayer<'_>,
ids: &mut Ids<'_>,
target: &mut EcGroup,
col: &mut Collector,
) {
for (i, atom) in layer.mask_atoms().iter().enumerate() {
let shown = atom.mask.name.clone().unwrap_or_else(|| format!("Mask {}", i.saturating_add(1)));
let what = format!("{comp}: '{layer_name}' {shown}");
if let Some(g) = import_mask(atom, i, &shown, &what, ml, ids, col) {
target.children.push(Node::Group(g));
col.imported.masks = col.imported.masks.saturating_add(1);
}
}
}
fn import_mask(atom: &MaskAtom<'_, '_>, index: usize, name: &str, what: &str, ml: MaskLayer<'_>, ids: &mut Ids<'_>, col: &mut Collector) -> Option<EcGroup> {
let MaskLayer { size, source, tm } = ml;
let m = &atom.mask;
// The path: the first shape (the static path, or the shape of the first key). A mask atom
// without a Mask Path entry is a mask whose path was never set: After Effects reads it back as
// the layer's source rectangle (900; 901 renders it shrunk by its expansion).
let unset = atom.path_shapes.is_empty() && atom.atom.get("ADBE Mask Shape").is_none();
let first = match atom.path_shapes.first() {
Some(Some(s)) => to_path(s, size),
Some(None) => Err("its path is unreadable"),
None if unset && source => Ok(source_rectangle(size)),
None if unset => Err("it has no path (the default path of a layer without a source is not sampled)"),
None => Err("it has no path"),
};
let first = match first {
Ok(p) => p,
Err(why) => {
col.lose_with(LossCategory::Masks, || format!("{what}: not imported, {why}"));
return None;
}
};
let mask_mode = match m.mode {
Some(code) => mode(code).unwrap_or_else(|| {
let shown = match code {
AepMode::Other(c) => c,
_ => 0,
};
col.lose_with(LossCategory::Masks, || format!("{what}: mode code {shown} is not known, imported as Add"));
MaskMode::Add
}),
None => {
col.lose_with(LossCategory::DamagedData, || format!("{what}: mode and invert switch unreadable, Add used"));
MaskMode::Add
}
};
let color = build::MASK_COLORS.get(index % build::MASK_COLORS.len()).copied().unwrap_or([0xb1, 0xb4, 0x4f]);
let mut g = build::mask(ids, name, first, mask_mode, color);
if let GroupKind::Mask { inverted, .. } = &mut g.kind {
*inverted = m.inverted.unwrap_or(false);
}
// The path keyframes.
if let (Some(path), Some(prop)) = (atom.path, g.get_mut("path")) {
if m.path_animated {
import_path_keys(&atom.path_shapes, &path, what, size, tm, prop, col);
}
import_expression(&path, prop, col);
}
// Feather, opacity and expansion.
let feather = m.feather;
set_static(&mut g, "feather", Value::Vec2(feather.value), feather.source, |v| v.components().iter().all(|c| *c >= 0.0), what, col);
let opacity = m.opacity_percent;
set_static(&mut g, "opacity", Value::Scalar(opacity.value), opacity.source, |v| v.components().iter().all(|c| (0.0..=100.0).contains(c)), what, col);
let expansion = m.expansion;
set_static(&mut g, "expansion", Value::Scalar(expansion.value), expansion.source, |_| true, what, col);
for (match_name, id, kind) in [
("ADBE Mask Feather", "feather", Kind::MaskFeather),
("ADBE Mask Opacity", "opacity", Kind::MaskOpacity),
("ADBE Mask Offset", "expansion", Kind::MaskExpansion),
] {
let Some(PropNode::Property(node)) = atom.atom.get(match_name) else { continue };
let Some(prop) = g.get_mut(id) else { continue };
if node.is_animated() {
import_keys(&node, kind, what, match_name, tm, prop, col);
}
import_expression(&node, prop, col);
}
Some(g)
}
/// Sets the static mask value `id` when it is valid; otherwise the default stays and it is reported.
fn set_static(g: &mut EcGroup, id: &str, value: Value, source: ValueSource, valid: impl Fn(&Value) -> bool, what: &str, col: &mut Collector) {
match source {
ValueSource::Default | ValueSource::Keyframed => {}
ValueSource::Unreadable => col.lose_with(LossCategory::DamagedData, || format!("{what}: {id} unreadable, default used")),
ValueSource::Stored => {
if crate::import::props::sane(&value) && valid(&value) {
if let Some(p) = g.get_mut(id) {
p.value = value;
}
} else {
col.lose_with(LossCategory::DamagedData, || format!("{what}: {id} holds a number that is not valid, default used"));
}
}
}
}
/// The path keyframes: key `i` of the path property with shape `i` of `omks` (`shapes`); `size`
/// scales the stored box (the source size for masks, 1 x 1 for shape paths, whose box is pixels).
pub(crate) fn import_path_keys(
shapes: &[Option<AepPath>],
path: &crate::Property<'_, '_>,
what: &str,
size: (u32, u32),
tm: &TimeMap,
prop: &mut effectcraft_project::Property,
col: &mut Collector,
) {
let Some(list) = path.keys() else {
col.lose_with(LossCategory::DamagedData, || format!("{what}: path keyframes unreadable, the first shape is static"));
return;
};
let records: Vec<_> = list.keyframes().collect();
if records.len() != shapes.len() {
col.lose_with(LossCategory::DamagedData, || format!("{what}: {} path keyframes but {} shapes, the first shape is static", records.len(), shapes.len()));
return;
}
let scale = path.time_scale().filter(|s| *s != 0).unwrap_or(tm.timescale);
let mut keys: Vec<Keyframe> = Vec::new();
for (rec, shape) in records.iter().zip(shapes) {
let Some(units) = rec.time_units() else {
col.lose_with(LossCategory::DamagedData, || format!("{what}: unreadable path keyframe"));
continue;
};
let path = match shape.as_ref().ok_or("its shape is unreadable").and_then(|s| to_path(s, size)) {
Ok(p) => p,
Err(why) => {
col.lose_with(LossCategory::DamagedData, || format!("{what}: a path keyframe was dropped, {why}"));
continue;
}
};
let mut key = Keyframe::new(tm.units(i64::from(units), scale), Value::Path(path));
key.in_interp = interp(rec.interpolation_in(), col, what);
key.out_interp = interp(rec.interpolation_out(), col, what);
if key.in_interp == Interp::Bezier || key.out_interp == Interp::Bezier {
// The ease at byte 24 (599, 700): influences as fractions; a speed of 0 is exact, the
// unit of another speed is not verified (taken as progress per second).
// The same rule as every other key's ease (`props::ease`): a speed beyond its limit is
// unreadable, not imported as it is.
match rec.ease().and_then(path_eases) {
Some((in_e, out_e)) => {
let unverified = (key.in_interp == Interp::Bezier && in_e.speed != 0.0) || (key.out_interp == Interp::Bezier && out_e.speed != 0.0);
if key.in_interp == Interp::Bezier {
key.in_ease = vec![in_e];
}
if key.out_interp == Interp::Bezier {
key.out_ease = vec![out_e];
}
if unverified {
col.lose_with(LossCategory::ApproximatedKeyframes, || {
format!("{what}: path key ease speed imported unverified (only speed 0 is sampled)")
});
}
}
None => {
col.lose_with(LossCategory::ApproximatedKeyframes, || format!("{what}: bezier path key read as linear (its ease is unreadable)"));
key.in_interp = if key.in_interp == Interp::Bezier { Interp::Linear } else { key.in_interp };
key.out_interp = if key.out_interp == Interp::Bezier { Interp::Linear } else { key.out_interp };
}
}
}
key.roving = rec.is_roving().unwrap_or(false);
key.label = rec.label().filter(|l| *l <= 16).unwrap_or(0);
keys.push(key);
}
if keys.is_empty() {
return;
}
sort_unique(&mut keys, what, "path keyframes", col);
// The first key's incoming and the last key's outgoing ease mean nothing.
if let Some(first) = keys.first_mut() {
first.in_ease.clear();
}
if let Some(last) = keys.last_mut() {
last.out_ease.clear();
}
col.imported.keyframes = col.imported.keyframes.saturating_add(keys.len());
if let Some(first) = keys.first() {
prop.value = first.value.clone();
}
prop.keys = keys;
}
/// The in and out ease of a mask path key, under the rule of every other key's ease
/// (`props::ease`); `None` when either side cannot be used.
fn path_eases(e: crate::KeyEase) -> Option<(effectcraft_keyframe::Ease, effectcraft_keyframe::Ease)> {
Some((ease(e.in_speed, e.in_influence, 1.0)?, ease(e.out_speed, e.out_influence, 1.0)?))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_path_ease_speed_beyond_the_property_limit_is_unreadable() {
let e = |speed: f64| crate::KeyEase { in_speed: speed, in_influence: 0.5, out_speed: 0.0, out_influence: 2.0 };
let (i, o) = path_eases(e(3.0)).expect("usable");
assert_eq!((i.speed, i.influence, o.speed, o.influence), (3.0, 0.5, 0.0, 1.0));
// Finite but far beyond what a property key accepts (before, only finiteness was checked).
assert!(path_eases(e(1e12)).is_none());
assert!(path_eases(e(-1e12)).is_none());
assert!(path_eases(e(f64::NAN)).is_none());
assert!(path_eases(crate::KeyEase { out_speed: 1e12, ..e(0.0) }).is_none());
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.