665bfac0b339
text.rs
//! Text layers: the text document (`btdk`) as a Source Text value, and everything of a text layer
//! that is not imported, reported.
//!
//! Mapped: the text (paragraphs separated by `\r`; U+0003, which After Effects lays out exactly
//! like `\r`, becomes `\r`), per style run the font (its PostScript name,
//! which EffectCraft resolves like a family name), size, fill and stroke colour, whether fill and
//! stroke are drawn, the stroke width, tracking, leading (automatic or explicit), faux bold /
//! italic, all caps / small caps, superscript / subscript, horizontal and vertical scale, baseline
//! shift, automatic kerning (metrics, optical, none), ligatures, tsume; per paragraph the
//! justification (also the justified variants), indents, space before / after, direction,
//! composer and hanging punctuation; stroke over fill (one switch for the whole text in
//! EffectCraft); box text as a box; vertical right-to-left text. A missing font keeps its name (the
//! renderer falls back as for any missing font) and is listed in the report.
use crate::{AutoKern, Caps, FontBaseline, Justification, Layer as AepLayer, ParagraphRun, PropGroup, PropNode, StyleRun as AepRun, TextDocument};
use effectcraft_keyframe::text_doc::{BaselineOption, CharStyle, Composer, Direction, Justify, Kerning, ParaStyle, StyleRun, TextDoc};
use effectcraft_project::Property;
use crate::import::props::import_expression;
use crate::import::report::{Collector, LossCategory};
/// How deep the walk over the text property groups goes.
const MAX_DEPTH: usize = 32;
/// The longest text kept (characters); longer text is cut and reported.
pub(crate) const MAX_TEXT_CHARS: usize = 1 << 20;
/// U+0003 (END OF TEXT): After Effects' other paragraph break besides `\r`.
const ETX: char = '\u{3}';
/// The name of a text layer without a name of its own: its first paragraph, cut as EffectCraft
/// cuts a following name ([`effectcraft_project::text_layer_name`]), so a following name that
/// export writes as no name comes back unchanged (#3233). U+0003 ends a paragraph like `\r`.
pub(crate) fn first_paragraph(raw: &str) -> String {
effectcraft_project::text_layer_name(raw.split(ETX).next().unwrap_or_default())
}
/// The Source Text value of `doc`, with what cannot be mapped reported for the layer `what`.
pub(crate) fn text_doc(doc: &TextDocument, what: &str, has_font: &dyn Fn(&str) -> bool, col: &mut Collector) -> TextDoc {
// The stored text ends with the `\r` of the last paragraph; EffectCraft's text does not.
let stored = doc.raw_text.strip_suffix('\r').unwrap_or(&doc.raw_text);
// U+0003 is a line break that starts a new paragraph in After Effects (386 against 387: the
// same two lines and two paragraphs, and the same paragraph runs as a CR). One character for
// one character of the same byte length, so the runs and the length check below stay aligned.
let text: String = stored.chars().take(MAX_TEXT_CHARS).map(|c| if c == ETX { '\r' } else { c }).collect();
if text.len() < stored.len() {
col.lose(LossCategory::DamagedData, format!("{what}: the text is longer than {MAX_TEXT_CHARS} characters and was cut"));
}
report_control_characters(&text, what, col);
let chars = text.chars().count();
let mut out = TextDoc { text, ..TextDoc::default() };
// Character runs, cut to the text (the last stored run also covers the final `\r`).
let mut runs = Vec::with_capacity(doc.style_runs.len());
let mut at = 0usize;
for run in &doc.style_runs {
if at >= chars {
break;
}
let len = run.length.min(chars - at);
let style = char_style(doc, run, what, has_font, col);
runs.push(StyleRun { len, style });
at = at.saturating_add(len);
}
if runs.is_empty()
&& let Some(first) = doc.style_runs.first()
{
// Empty text: the first run's style is the style text typed into it gets.
runs.push(StyleRun { len: 0, style: char_style(doc, first, what, has_font, col) });
}
if let Some(last) = runs.last_mut()
&& at < chars
{
last.len = last.len.saturating_add(chars - at);
}
if runs.is_empty() {
col.lose(LossCategory::DamagedData, format!("{what}: the text has no readable character style, the default style is used"));
} else {
out.set_runs(runs);
}
// Paragraph settings, one per stored paragraph.
let paras: Vec<ParaStyle> = doc.paragraphs.iter().map(|p| para_style(p, what, col)).collect();
if !paras.is_empty() {
out.set_paras(paras);
}
// Stroke over fill is one switch for the whole text in EffectCraft (per run in After Effects).
if let Some(first) = doc.style_runs.first() {
out.stroke_over_fill = first.stroke_over_fill;
if doc.style_runs.iter().any(|r| r.stroke_over_fill != first.stroke_over_fill && r.apply_stroke) {
col.lose(LossCategory::TextLayers, format!("{what}: stroke over fill differs between characters, the first character's order is used"));
}
}
if !doc.kerning.is_empty() {
col.lose(LossCategory::TextLayers, format!("{what}: manual kerning is not imported"));
}
match doc.line_orientation {
None => {}
// Vertical, right to left (575).
Some(2) => out.vertical = true,
Some(code) => col.lose(LossCategory::TextLayers, format!("{what}: line orientation {code} is not decoded, imported as horizontal")),
}
report_character_extras(doc, what, col);
if let Some(b) = doc.text_box {
let finite = [b.x, b.y, b.width, b.height].iter().all(|v| v.is_finite() && v.abs() <= crate::import::props::LIMIT);
if finite {
out.box_pos = [b.x, b.y];
out.box_size = Some([b.width.max(1.0), b.height.max(1.0)]);
} else {
col.lose(LossCategory::DamagedData, format!("{what}: the text box is not valid, imported as point text"));
}
}
if doc.incomplete_runs > 0 {
col.lose(
LossCategory::DamagedData,
format!("{what}: {} damaged text style or paragraph runs (their missing values were taken from the run before)", doc.incomplete_runs),
);
}
if !doc.undecoded_style_fields.is_empty() {
col.lose(
LossCategory::TextLayers,
format!("{what}: character style fields not imported (they differ from the default): /{}", doc.undecoded_style_fields.join(" /")),
);
}
if !doc.undecoded_paragraph_fields.is_empty() {
col.lose(
LossCategory::TextLayers,
format!("{what}: paragraph fields not imported (they differ from the default): /{}", doc.undecoded_paragraph_fields.join(" /")),
);
}
out
}
/// Control characters other than the paragraph break (`\r`, and U+0003, mapped to it before) are
/// kept but reported: their meaning is not sampled.
fn report_control_characters(text: &str, what: &str, col: &mut Collector) {
let mut seen: Vec<char> = Vec::new();
for c in text.chars().filter(|c| c.is_control() && !matches!(c, '\r' | '\n' | '\t')) {
if !seen.contains(&c) && seen.len() < 8 {
seen.push(c);
}
}
if !seen.is_empty() {
let list: Vec<String> = seen.iter().map(|c| format!("U+{:04X}", u32::from(*c))).collect();
col.lose(
LossCategory::TextLayers,
format!("{what}: the text contains control characters whose meaning is not decoded ({}); they are kept as they are", list.join(", ")),
);
}
}
fn finite(v: f64, lo: f64, hi: f64) -> Option<f64> {
v.is_finite().then(|| v.clamp(lo, hi))
}
/// `v` within `lo..=hi`: a value outside is clamped, a value that is not a number is replaced by
/// `default`, and both are reported (a normal file stays inside the limits).
fn fit(v: f64, (lo, hi): (f64, f64), default: f64, field: &str, what: &str, col: &mut Collector) -> f64 {
if !v.is_finite() {
col.lose(LossCategory::TextLayers, format!("{what}: {field} is not a number, {default} is used"));
return default;
}
let fitted = v.clamp(lo, hi);
if (fitted - v).abs() > 1e-9 {
col.lose(LossCategory::TextLayers, format!("{what}: {field} {v} is outside {lo}..{hi}, {fitted} is used"));
}
fitted
}
fn rgba(argb: [f64; 4]) -> Option<[f32; 4]> {
let [a, r, g, b] = argb;
let c = |v: f64| v.is_finite().then(|| v.clamp(0.0, 1.0) as f32);
Some([c(r)?, c(g)?, c(b)?, c(a)?])
}
/// Reports a colour whose channels [`rgba`] clipped to `0..=1` (a normal file stays inside; as in
/// [`fit`], float noise of 1e-9 is not reported).
fn clipped(argb: [f64; 4], which: &str, what: &str, col: &mut Collector) {
let outside: Vec<String> = argb.iter().filter(|v| !(-1e-9..=1.0 + 1e-9).contains(*v)).map(|v| v.to_string()).collect();
if !outside.is_empty() {
col.lose(LossCategory::TextLayers, format!("{what}: a {which} colour channel is outside 0..1 ({}), clipped", outside.join(", ")));
}
}
fn char_style(doc: &TextDocument, run: &AepRun, what: &str, has_font: &dyn Fn(&str) -> bool, col: &mut Collector) -> CharStyle {
let mut s = CharStyle::default();
match doc.font_of(run) {
Some(font) => {
s.font = font.to_string();
if !col.missing_fonts.iter().any(|f| f == font) && !has_font(font) {
col.missing_fonts.push(font.to_string());
}
}
None => col.lose(LossCategory::DamagedData, format!("{what}: a style run names no readable font, the default font is used")),
}
s.style = "Regular".to_string();
s.size = fit(run.font_size, (0.1, 10_000.0), s.size, "the font size", what, col);
match rgba(run.fill_argb) {
Some(c) => {
s.fill = c;
clipped(run.fill_argb, "fill", what, col);
}
None => col.lose(LossCategory::DamagedData, format!("{what}: a fill colour is not valid, the default is used")),
}
if let Some(argb) = run.stroke_argb {
match rgba(argb) {
Some(c) => {
s.stroke = c;
clipped(argb, "stroke", what, col);
}
None => col.lose(LossCategory::DamagedData, format!("{what}: a stroke colour is not valid, the default is used")),
}
}
// Whether fill and stroke are drawn and the stroke width (544-546).
s.apply_fill = run.apply_fill;
s.apply_stroke = run.apply_stroke;
s.stroke_width = fit(run.stroke_width, (0.0, 10_000.0), 0.0, "the stroke width", what, col);
s.tracking = fit(run.tracking, (-100_000.0, 100_000.0), 0.0, "the tracking", what, col);
// Scales are factors in the file (539, 540) and percent in EffectCraft; tsume is a fraction
// (553) and a percentage.
s.h_scale = fit(run.horizontal_scale * 100.0, (1.0, 10_000.0), 100.0, "the horizontal scale", what, col);
s.v_scale = fit(run.vertical_scale * 100.0, (1.0, 10_000.0), 100.0, "the vertical scale", what, col);
s.baseline_shift = fit(run.baseline_shift, (-100_000.0, 100_000.0), 0.0, "the baseline shift", what, col);
s.tsume = fit(run.tsume * 100.0, (0.0, 100.0), 0.0, "the tsume", what, col);
s.ligatures = run.ligatures;
s.kerning = match run.auto_kern {
AutoKern::Metrics => Kerning::Metrics,
AutoKern::Optical => Kerning::Optical,
// No automatic kerning: a manual amount of 0 replaces the metrics (542).
AutoKern::None => Kerning::Manual(0.0),
AutoKern::Other(code) => {
col.lose(LossCategory::TextLayers, format!("{what}: kerning code {code} is not decoded, metrics kerning used"));
Kerning::Metrics
}
};
s.leading = if run.auto_leading { None } else { run.leading.and_then(|l| finite(l, 0.0, 100_000.0)) };
s.faux_bold = run.faux_bold;
s.faux_italic = run.faux_italic;
match run.caps {
Caps::Normal => {}
Caps::All => s.all_caps = true,
Caps::Small => s.small_caps = true,
Caps::Other(code) => col.lose(LossCategory::TextLayers, format!("{what}: capitalisation code {code} is not decoded, imported as normal")),
}
// Superscript / subscript (526-528): After Effects' 58.3 % size and 33.3 % shift are
// EffectCraft's too.
s.baseline = match run.baseline {
FontBaseline::Normal => BaselineOption::Normal,
FontBaseline::Superscript => BaselineOption::Superscript,
FontBaseline::Subscript => BaselineOption::Subscript,
FontBaseline::Other(code) => {
col.lose(LossCategory::TextLayers, format!("{what}: superscript / subscript code {code} is not decoded, imported as normal"));
BaselineOption::Normal
}
};
s
}
/// The paragraph settings of one stored paragraph.
fn para_style(p: &ParagraphRun, what: &str, col: &mut Collector) -> ParaStyle {
let px = |v: f64| finite(v, -100_000.0, 100_000.0).unwrap_or(0.0);
if p.leading_type != 0 {
col.lose(LossCategory::TextLayers, format!("{what}: the Japanese leading model is not imported, Roman leading used"));
}
// Automatic hyphenation (`/9`) is not reported: EffectCraft never hyphenates, so a paragraph
// with hyphenation off (556) is laid out as After Effects does.
let rtl = p.direction == 1;
ParaStyle {
justify: justify(p.justification, rtl, what, col),
indent_left: px(p.start_indent),
indent_right: px(p.end_indent),
indent_first: px(p.first_line_indent),
space_before: px(p.space_before),
space_after: px(p.space_after),
direction: match p.direction {
0 => Direction::Ltr,
1 => Direction::Rtl,
code => {
col.lose(LossCategory::TextLayers, format!("{what}: paragraph direction {code} is not decoded, left to right used"));
Direction::Ltr
}
},
// A new After Effects text uses the single-line composer (`/29` false, 557, 559).
composer: if p.every_line_composer { Composer::EveryLine } else { Composer::SingleLine },
hanging_punctuation: p.hanging_roman,
}
}
/// Character settings EffectCraft has no field for, reported once per text.
fn report_character_extras(doc: &TextDocument, what: &str, col: &mut Collector) {
let runs = &doc.style_runs;
if runs.iter().any(|r| r.no_break) {
col.lose(LossCategory::TextLayers, format!("{what}: No Break is not imported"));
}
if runs.iter().any(|r| r.apply_stroke && r.line_join != 0) {
col.lose(LossCategory::TextLayers, format!("{what}: the stroke line join is not imported, miter used"));
}
// Digit set 1 (Arabic) lays out Latin digits as the default does (571: same bounds of `1234`).
if runs.iter().any(|r| r.digit_set > 1 || r.digit_set < 0) {
col.lose(LossCategory::TextLayers, format!("{what}: the digit set is not imported"));
}
// The baseline direction only matters for vertical text.
if doc.line_orientation.is_some() {
let tcy = runs.iter().any(|r| r.baseline_direction == 3);
if tcy || runs.iter().any(|r| r.baseline_direction != 1 && r.baseline_direction != 3) {
col.lose(LossCategory::TextLayers, format!("{what}: the baseline direction of vertical text is not imported"));
}
}
}
/// The stored justification is relative to the paragraph direction: in a right-to-left paragraph
/// After Effects lays "left" (0) and "justify, last line left" (3) out flush right and "right"
/// (1, 4) flush left (read-back test t7: point and box text with all seven codes; 2, 5 and 6 are
/// the same in both directions). EffectCraft's justification is visual, so the two pairs swap.
fn justify(j: Justification, rtl: bool, what: &str, col: &mut Collector) -> Justify {
match j {
Justification::Left if rtl => Justify::Right,
Justification::Right if rtl => Justify::Left,
Justification::FullLeft if rtl => Justify::JustifyLastRight,
Justification::FullRight if rtl => Justify::JustifyLastLeft,
Justification::Left => Justify::Left,
Justification::Right => Justify::Right,
Justification::Center => Justify::Center,
Justification::FullLeft => Justify::JustifyLastLeft,
Justification::FullRight => Justify::JustifyLastRight,
Justification::FullCenter => Justify::JustifyLastCenter,
Justification::FullAll => Justify::JustifyAll,
Justification::Other(code) => {
col.lose(LossCategory::TextLayers, format!("{what}: justification code {code} is not decoded, imported as left"));
Justify::Left
}
}
}
/// Whether a group holds any stored value (a set, keyed or expression property).
fn has_stored(g: &PropGroup<'_, '_>, depth: usize) -> bool {
if depth > MAX_DEPTH {
return true;
}
g.entries().iter().any(|e| match e.node {
PropNode::Group(sub) => has_stored(&sub, depth.saturating_add(1)),
PropNode::Property(p) => p.flags() == Some(1) || p.is_animated() || p.expression().is_some(),
PropNode::Other(_) => false,
})
}
/// The Source Text expression into `target` (the layer's `text/sourceText`). The Source Text
/// record keeps it like any other property: the text in its `Utf8`, the flags in its `tdb4`
/// (`tests/fixtures/text-synthetic.aep`). An expression whose flags are unreadable, or a layer
/// without a Source Text property, is reported.
pub(crate) fn import_source_text_expression(layer: &AepLayer<'_, '_>, target: Option<&mut Property>, what: &str, col: &mut Collector) {
let Some(st) = layer.source_text_property() else { return };
if st.expression().is_none() {
return;
}
match target {
Some(p) if st.expression_enabled().is_some() => import_expression(&st, p, col),
_ => col.lose(LossCategory::TextLayers, format!("{what}: the Source Text expression is not imported")),
}
}
/// The parts of a text layer besides its first text document that are not imported.
pub(crate) fn report_text_extras(layer: &AepLayer<'_, '_>, what: &str, col: &mut Collector) {
if let Some(st) = layer.source_text_property()
&& (st.is_animated() || layer.text_document_count() > 1)
{
col.lose(LossCategory::TextLayers, format!("{what}: Source Text keyframes are not imported (the first text document is)"));
}
let Some(PropNode::Group(text)) = layer.properties().and_then(|p| p.get("ADBE Text Properties")) else { return };
for e in text.entries() {
let PropNode::Group(g) = e.node else { continue };
match e.match_name.as_str() {
// Imported by `text_anim::import_animators`.
"ADBE Text Animators" => {}
"ADBE Text Path Options" if has_stored(&g, 0) => col.lose(LossCategory::TextLayers, format!("{what}: Path Options are not imported")),
"ADBE Text More Options" if has_stored(&g, 0) => col.lose(LossCategory::TextLayers, format!("{what}: More Options are not imported")),
_ => {}
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn values_outside_their_limits_are_fitted_and_reported() {
let mut col = Collector::default();
// Inside the limits, and the edge itself: nothing to report.
assert_eq!(fit(12.0, (0.1, 10_000.0), 1.0, "the font size", "t", &mut col), 12.0);
assert_eq!(fit(100.0, (1.0, 10_000.0), 100.0, "the scale", "t", &mut col), 100.0);
assert!(col.finish().is_lossless());
// Clamped, and a number that is none.
let mut col = Collector::default();
assert_eq!(fit(1.0e9, (0.1, 10_000.0), 1.0, "the font size", "t", &mut col), 10_000.0);
assert_eq!(fit(f64::NAN, (-5.0, 5.0), 0.0, "the tracking", "t", &mut col), 0.0);
let report = col.finish();
let details: Vec<_> = report.losses.iter().flat_map(|l| l.details.iter().cloned()).collect();
assert_eq!(details.len(), 2, "{details:?}");
assert!(details[0].contains("outside") && details[1].contains("not a number"), "{details:?}");
}
#[test]
fn colour_channels_outside_0_to_1_are_clipped_and_reported() {
// A fill channel of 2.0 used to become 1.0 silently.
let mut col = Collector::default();
let argb = [1.0, 2.0, 0.5, -0.25];
assert_eq!(rgba(argb), Some([1.0, 0.5, 0.0, 1.0]));
clipped(argb, "fill", "t", &mut col);
let report = col.finish();
assert_eq!(report.count(LossCategory::TextLayers), 1, "{:?}", report.losses);
let detail = &report.losses[0].details[0];
assert!(detail.contains("fill colour") && detail.contains('2') && detail.contains("-0.25"), "{detail}");
// Inside the range, and its edges: nothing to report.
let mut col = Collector::default();
clipped([1.0, 0.0, 0.5, 1.0], "stroke", "t", &mut col);
assert!(col.finish().is_lossless());
// Not a number: no colour (the caller reports that as damage).
assert_eq!(rgba([1.0, f64::NAN, 0.0, 0.0]), None);
}
/// A document with one style run, `run`, over the text "A".
fn doc_with(run: AepRun) -> TextDocument {
TextDocument {
text: "A".into(),
raw_text: "A\r".into(),
font_size: run.font_size,
fill_argb: run.fill_argb,
font_index: 0,
font: Some("F".into()),
fonts: vec!["F".into()],
paragraphs: Vec::new(),
style_runs: vec![AepRun { length: 2, ..run }],
text_box: None,
incomplete_runs: 0,
undecoded_style_fields: Vec::new(),
undecoded_paragraph_fields: Vec::new(),
kerning: Vec::new(),
line_orientation: None,
}
}
#[test]
fn a_text_layer_reports_its_clipped_fill_and_stroke() {
let any_font = |_: &str| true;
// The sampled run imports without a text loss.
let mut col = Collector::default();
text_doc(&doc_with(AepRun::SAMPLED), "t", &any_font, &mut col);
assert_eq!(col.finish().count(LossCategory::TextLayers), 0);
// A fill red of 2.0 and a stroke blue of -1: imported as 1 and 0, both reported.
let mut col = Collector::default();
let run = AepRun { fill_argb: [1.0, 2.0, 0.0, 0.0], stroke_argb: Some([1.0, 0.0, 0.0, -1.0]), ..AepRun::SAMPLED };
let doc = text_doc(&doc_with(run), "t", &any_font, &mut col);
let report = col.finish();
let details: Vec<_> = report.losses.iter().flat_map(|l| l.details.iter().cloned()).collect();
assert!(details.iter().any(|d| d.contains("fill colour channel")), "{details:?}");
assert!(details.iter().any(|d| d.contains("stroke colour channel")), "{details:?}");
// One run: its style is the document's own.
assert!(doc.runs.is_empty());
assert_eq!((doc.fill[0], doc.stroke[2]), (1.0, 0.0));
// A stroke that is not a number is damage, as the fill already was.
let mut col = Collector::default();
text_doc(&doc_with(AepRun { stroke_argb: Some([1.0, f64::NAN, 0.0, 0.0]), ..AepRun::SAMPLED }), "t", &any_font, &mut col);
assert!(col.finish().count(LossCategory::DamagedData) == 1);
}
}
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.