write_text_path.rs

//! Sets lines of text along paths: round a seal, over an arch, straight across.
//!
//! A path is given in the same words a glyph's own outline is given in, so the
//! curve a font already knows how to describe is the curve a line of text
//! follows. The path is walked by length, so two letters an inch apart along it
//! are an inch apart on the page whatever the curve does between them.
//!
//! The page below draws a seal with a legend curving over its top and another
//! bowed inside its foot, a title bent over an arch, and three straight paths
//! that show where a line begins: at the head of the path, halfway along it, or
//! at its far end. The straight paths are drawn as thin rules, so the line and
//! the path it follows can be read against each other.
//!
//! The title, the legends and the captions are held in `Words`, once per
//! language, and `HQF_PDF_LANG` picks which set is drawn.
//!
//! Usage: `cargo run --example write_text_path -- tmp/text_path.pdf`
//!        `HQF_PDF_LANG=fr cargo run --example write_text_path -- tmp/chemin.pdf`

use std::env;
use std::fs;
use std::path::{Path, PathBuf};

use hqf_pdf::content::Content;
use hqf_pdf::font::outline::Segment;
use hqf_pdf::layout::{PathStart, TextFlow, TextPath};
use hqf_pdf::{Document, Font, FontHandle, Page, Rgb};

#[path = "shared/out.rs"]
mod out;

#[path = "shared/licence.rs"]
mod licence;

#[path = "shared/language.rs"]
mod language;

#[path = "shared/failure.rs"]
mod failure;

use language::Language;

/// The font the example draws with.
fn default_font() -> PathBuf {
    Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("tests")
        .join("fonts")
        .join("DejaVuSans.ttf")
}

/// The margin the page is laid out inside.
const MARGIN: f64 = 56.0;

/// How far the page runs across, between the margins.
const WIDTH: f64 = 483.0;

/// Where the seal stands.
const SEAL: (f64, f64) = (297.5, 620.0);

/// The outer ring of the seal, in points.
const RING: f64 = 118.0;

/// The inner ring, which the legend is written between.
const INNER_RING: f64 = 98.0;

/// The circle the legend over the seal is set on.
const LEGEND: f64 = 101.0;

/// How far a circle's control points stand from its quarter marks, as a share
/// of the radius: the number that turns four cubics into a circle.
const KAPPA: f64 = 0.552_284_749_830_793_4;

/// The four quarter marks of a circle of radius one, anticlockwise from due
/// east.
const MARKS: [(f64, f64); 4] = [(1.0, 0.0), (0.0, 1.0), (-1.0, 0.0), (0.0, -1.0)];

/// How many straight paths the page sets a line along.
const STARTS: usize = 3;

/// How many lines the page sets along a path: the two legends of the seal, the
/// one over the arch, and one on each straight path.
const ALONG_A_PATH: usize = 3 + STARTS;

/// Where each of the three straight paths runs.
const RULES: [f64; STARTS] = [250.0, 200.0, 150.0];

/// The three places along a path a line can begin, in the order `RULES` draws
/// them.
const BEGINNINGS: [PathStart; STARTS] = [PathStart::Beginning, PathStart::Middle, PathStart::End];

/// Where each caption's box starts, in the order `Words` holds them.
const CAPTIONS: [f64; STARTS] = [480.0, 300.0, 118.0];

/// The words the page is written in, one set per language.
#[derive(Debug)]
struct Words {
    /// The line at the head of the page.
    title: &'static str,
    /// The legend curving over the top of the seal.
    seal_over: &'static str,
    /// The legend bowed inside the foot of the seal.
    seal_under: &'static str,
    /// The line bent over the arch.
    arch: &'static str,
    /// What is set along each of the three straight paths.
    starts: [&'static str; STARTS],
    /// What is written under the seal, the arch and the three rules.
    captions: [&'static str; STARTS],
}

impl Words {
    /// The words the page is written in, in `language`.
    fn of(language: Language) -> &'static Self {
        language::pick(&WORDS, language)
    }
}

/// The page in English.
const ENGLISH: Words = Words {
    title: "Text set along a path",
    seal_over: "HQF DEVELOPMENT",
    seal_under: "CERTIFIED COPY",
    arch: "A line bent over an arch",
    starts: [
        "At the head of the path",
        "Halfway along it",
        "Stopping where it stops",
    ],
    captions: [
        "The legend follows the ring: over the top it curves with the seal, and \
         at the foot the path bows the other way, so that the words there stand \
         upright instead of hanging upside down.",
        "One curve, one line. The path is a single cubic, and the line is set \
         from its middle, so that what is written stays centred on the arch \
         however long the words are.",
        "The same words on the same path, begun in three places: at its head, \
         halfway along it, and stopping where it stops. The rule under each is \
         the path itself.",
    ],
};

/// The page in French.
const FRENCH: Words = Words {
    title: "Du texte posé le long d'un chemin",
    seal_over: "HQF DEVELOPMENT",
    seal_under: "COPIE CERTIFIÉE",
    arch: "Une ligne courbée sur une arche",
    starts: [
        "Au départ du chemin",
        "À mi-chemin",
        "S'arrêtant où il s'arrête",
    ],
    captions: [
        "La légende suit l'anneau : au-dessus, elle épouse le sceau ; au pied, \
         le chemin se creuse dans l'autre sens, pour que les mots s'y tiennent \
         droits au lieu de pendre à l'envers.",
        "Une courbe, une ligne. Le chemin est une seule cubique, et la ligne \
         part de son milieu : ce qui est écrit reste centré sur l'arche quelle \
         que soit la longueur des mots.",
        "Les mêmes mots sur le même chemin, commencés à trois endroits : à son \
         départ, à mi-chemin, et s'arrêtant où il s'arrête. Le filet sous \
         chacun est le chemin lui-même.",
    ],
};

/// Every language the example is written in. A language is added by writing its
/// own set of words and naming it here.
static WORDS: [(Language, &Words); 2] =
    [(Language::English, &ENGLISH), (Language::French, &FRENCH)];

/// A quarter of a circle of radius `radius` about the seal, running from the
/// quarter mark `from` to the quarter mark `next`.
///
/// The two marks are a quarter turn apart, in either order, so the same
/// arithmetic draws the circle anticlockwise and the legend clockwise over the
/// top of it.
fn arc(radius: f64, from: (f64, f64), next: (f64, f64)) -> Segment {
    let pull = KAPPA * radius;
    Segment::CurveTo {
        x1: next.0.mul_add(pull, from.0.mul_add(radius, SEAL.0)),
        y1: next.1.mul_add(pull, from.1.mul_add(radius, SEAL.1)),
        x2: from.0.mul_add(pull, next.0.mul_add(radius, SEAL.0)),
        y2: from.1.mul_add(pull, next.1.mul_add(radius, SEAL.1)),
        x: next.0.mul_add(radius, SEAL.0),
        y: next.1.mul_add(radius, SEAL.1),
    }
}

/// The path the legend over the seal follows: the left of the ring, over the
/// top, to the right of it.
fn over_the_seal() -> [Segment; 3] {
    [
        Segment::MoveTo {
            x: SEAL.0 - LEGEND,
            y: SEAL.1,
        },
        arc(LEGEND, MARKS[2], MARKS[1]),
        arc(LEGEND, MARKS[1], MARKS[0]),
    ]
}

/// The path the legend at the foot of the seal follows: one curve bowing
/// downward, so that the words along it stand upright.
fn under_the_seal() -> [Segment; 2] {
    [
        Segment::MoveTo {
            x: SEAL.0 - 80.0,
            y: SEAL.1 - 36.0,
        },
        Segment::CurveTo {
            x1: SEAL.0 - 34.0,
            y1: SEAL.1 - 96.0,
            x2: SEAL.0 + 34.0,
            y2: SEAL.1 - 96.0,
            x: SEAL.0 + 80.0,
            y: SEAL.1 - 36.0,
        },
    ]
}

/// The arch the title is bent over.
fn the_arch() -> [Segment; 2] {
    [
        Segment::MoveTo {
            x: MARGIN,
            y: 330.0,
        },
        Segment::CurveTo {
            x1: MARGIN + 145.0,
            y1: 420.0,
            x2: MARGIN + WIDTH - 145.0,
            y2: 420.0,
            x: MARGIN + WIDTH,
            y: 330.0,
        },
    ]
}

/// A path running straight across the page at `y`.
fn straight(y: f64) -> [Segment; 2] {
    [
        Segment::MoveTo { x: MARGIN, y },
        Segment::LineTo {
            x: MARGIN + WIDTH,
            y,
        },
    ]
}

/// Draws a ring of the seal.
fn ring(content: &mut Content, radius: f64) -> Result<(), hqf_pdf::Error> {
    content.move_to(SEAL.0 + radius, SEAL.1)?;
    for turn in 0..MARKS.len() {
        let Segment::CurveTo {
            x1,
            y1,
            x2,
            y2,
            x,
            y,
        } = arc(radius, MARKS[turn], MARKS[(turn + 1) % MARKS.len()])
        else {
            continue;
        };
        content.curve_to(x1, y1, x2, y2, x, y)?;
    }
    content.close_path();
    content.stroke();
    Ok(())
}

/// Draws a rule where a straight path runs.
fn rule(content: &mut Content, y: f64) -> Result<(), hqf_pdf::Error> {
    content.move_to(MARGIN, y)?;
    content.line_to(MARGIN + WIDTH, y)?;
    content.stroke();
    Ok(())
}

/// Writes a line of ordinary text at `(x, y)`.
fn write(
    content: &mut Content,
    font: &FontHandle,
    x: f64,
    y: f64,
    size: f64,
    text: &str,
) -> Result<(), hqf_pdf::Error> {
    content.begin_text();
    content.set_font(font, size)?;
    content.text_origin(x, y)?;
    content.show_glyphs(&font.glyphs(text));
    content.end_text();
    Ok(())
}

/// Writes a caption in a column the width of the page.
fn caption(
    content: &mut Content,
    font: &FontHandle,
    top: f64,
    color: Rgb,
    text: &str,
) -> Result<(), hqf_pdf::Error> {
    let flow = TextFlow::new(font, 8.5).leading(12.0).color(color);
    let lines = flow.break_lines(text, WIDTH);
    content.begin_text();
    flow.draw(content, &lines, MARGIN, top, WIDTH)?;
    content.end_text();
    Ok(())
}

fn main() -> std::process::ExitCode {
    failure::reported(run())
}

fn run() -> Result<(), Box<dyn std::error::Error>> {
    let language = Language::from_environment()?;
    let words = Words::of(language);

    // A named file is written as named; the default one carries the language,
    // so the two languages do not overwrite each other in `tmp/`.
    let out = env::args()
        .nth(1)
        .unwrap_or_else(|| language.file_name(&out::default_path("text_path")));

    let mut doc = Document::new();
    doc.set_license(licence::licensed());
    let font = doc.add_font(Font::parse(fs::read(default_font())?)?);

    let mut content = Content::new();
    write(&mut content, &font, MARGIN, 800.0, 14.0, words.title)?;

    content.save_state();
    content.set_stroke(Rgb::new(0.25, 0.35, 0.7))?;
    content.set_line_width(1.5)?;
    ring(&mut content, RING)?;
    ring(&mut content, INNER_RING)?;
    content.restore_state();

    content.save_state();
    content.set_fill(Rgb::new(0.25, 0.35, 0.7))?;
    TextPath::new(&font, words.seal_over, 14.0, &over_the_seal())?
        .start(PathStart::Middle)
        .draw(&mut content)?;
    TextPath::new(&font, words.seal_under, 12.0, &under_the_seal())?
        .start(PathStart::Middle)
        .draw(&mut content)?;
    content.restore_state();

    content.save_state();
    content.set_fill(Rgb::new(0.1, 0.45, 0.25))?;
    TextPath::new(&font, words.arch, 20.0, &the_arch())?
        .start(PathStart::Middle)
        .draw(&mut content)?;
    content.restore_state();

    content.save_state();
    content.set_stroke(Rgb::gray(0.8))?;
    content.set_line_width(0.5)?;
    for y in RULES {
        rule(&mut content, y)?;
    }
    content.restore_state();

    for ((y, start), text) in RULES.iter().zip(BEGINNINGS).zip(words.starts) {
        TextPath::new(&font, text, 12.0, &straight(*y))?
            .start(start)
            .draw(&mut content)?;
    }

    for (top, text) in CAPTIONS.iter().zip(words.captions) {
        caption(&mut content, &font, *top, Rgb::gray(0.35), text)?;
    }

    let mut page = Page::a4();
    page.content = content.into_bytes();
    doc.add_page(page)?;

    let bytes = doc.to_bytes()?;
    if let Some(parent) = Path::new(&out).parent() {
        fs::create_dir_all(parent)?;
    }
    fs::write(&out, &bytes)?;
    println!(
        "wrote {out}: {} bytes, {ALONG_A_PATH} lines along a path",
        bytes.len()
    );
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::{WORDS, language};

    /// The lines two languages write the same way: the brand is the brand in
    /// every language.
    const SPARED: [&str; 1] = [r#"seal_over: "HQF DEVELOPMENT""#];

    #[test]
    fn every_language_draws_the_page_in_its_own_words() {
        let untranslated = language::untranslated_lines(&WORDS, &SPARED);

        assert!(
            untranslated.is_empty(),
            "the page says these in more than one language: {untranslated:?}"
        );
    }
}