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",
        "Jusqu’au bout du chemin",
    ],
    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 est \
centrée sur son milieu : le texte reste centré sur l’arche, quelle que soit la \
longueur des mots.",
        "Les mêmes mots sur le même chemin, placés de trois façons : dès son départ, à \
mi-chemin, et jusqu’à son bout. Le filet sous chacun est le chemin lui-même.",
    ],
};

/// The page in Dutch.
const DUTCH: Words = Words {
    title: "Tekst gezet langs een pad",
    seal_over: "HQF DEVELOPMENT",
    seal_under: "GEWAARMERKTE KOPIE",
    arch: "Een regel gebogen over een boog",
    starts: [
        "Aan het begin van het pad",
        "Halverwege",
        "Stoppend waar het stopt",
    ],
    captions: [
        "Het onderschrift volgt de ring: bovenaan buigt het met het zegel mee, en onderaan buigt het pad de andere kant op, zodat de woorden daar rechtop staan in plaats van ondersteboven te hangen.",
        "Eén curve, één regel. Het pad is één kubische curve, en de regel wordt vanuit het midden gezet, zodat wat er staat gecentreerd blijft op de boog, hoe lang de woorden ook zijn.",
        "Dezelfde woorden op hetzelfde pad, op drie plekken begonnen: aan het begin, halverwege, en stoppend waar het stopt. De lijn onder elk is het pad zelf.",
    ],
};

/// The page in Portuguese.
const PORTUGUESE: Words = Words {
    title: "Texto composto ao longo de um traçado",
    seal_over: "HQF DEVELOPMENT",
    seal_under: "CÓPIA CERTIFICADA",
    arch: "Uma linha dobrada sobre um arco",
    starts: [
        "No início do traçado",
        "A meio caminho",
        "A parar onde ele para",
    ],
    captions: [
        "A legenda segue o anel: por cima curva com o selo, e no pé o traçado dobra-se ao contrário, para que as palavras aí fiquem direitas em vez de penderem de pernas para o ar.",
        "Uma curva, uma linha. O traçado é uma única cúbica, e a linha é composta a partir do seu meio, para que o que está escrito fique centrado no arco seja qual for o comprimento das palavras.",
        "As mesmas palavras no mesmo traçado, começadas em três sítios: no início, a meio caminho, e a parar onde ele para. O filete sob cada uma é o próprio traçado.",
    ],
};

/// The page in Italian.
const ITALIAN: Words = Words {
    title: "Testo composto lungo un tracciato",
    seal_over: "HQF DEVELOPMENT",
    seal_under: "COPIA CONFORME",
    arch: "Una riga curvata su un arco",
    starts: [
        "All’inizio del tracciato",
        "A metà strada",
        "Fermandosi dove si ferma",
    ],
    captions: [
        "La legenda segue l’anello: sopra si curva con il sigillo, e al piede il tracciato si piega al contrario, così le parole lì stanno dritte invece di pendere capovolte.",
        "Una curva, una riga. Il tracciato è una sola cubica, e la riga è composta dal suo centro, così ciò che è scritto resta centrato sull’arco per quanto lunghe siano le parole.",
        "Le stesse parole sullo stesso tracciato, iniziate in tre punti: all’inizio, a metà strada, e fermandosi dove si ferma. Il filetto sotto ciascuna è il tracciato stesso.",
    ],
};

/// The page in Spanish.
const SPANISH: Words = Words {
    title: "Texto compuesto a lo largo de un trazado",
    seal_over: "HQF DEVELOPMENT",
    seal_under: "COPIA CERTIFICADA",
    arch: "Una línea curvada sobre un arco",
    starts: [
        "Al principio del trazado",
        "A mitad de camino",
        "Acabando donde acaba",
    ],
    captions: [
        "La leyenda sigue el anillo: por arriba se curva con el sello, y en el pie el trazado se arquea al revés, para que las palabras de ahí queden derechas en vez de colgar cabeza abajo.",
        "Una curva, una línea. El trazado es una sola cúbica, y la línea se compone desde su centro, para que lo escrito quede centrado en el arco sea cual sea la longitud de las palabras.",
        "Las mismas palabras en el mismo trazado, empezadas en tres sitios: al principio, a mitad de camino, y acabando donde acaba el trazado. La raya bajo cada una es el propio trazado.",
    ],
};

/// The page in German.
const GERMAN: Words = Words {
    title: "Text entlang eines Pfads gesetzt",
    seal_over: "HQF DEVELOPMENT",
    seal_under: "BEGLAUBIGTE KOPIE",
    arch: "Eine Zeile, über einen Bogen gelegt",
    starts: [
        "Am Anfang des Pfads",
        "Auf halber Strecke",
        "Endet, wo er endet",
    ],
    captions: [
        "Die Umschrift folgt dem Ring: Oben krümmt sie sich mit dem Siegel, und am Fuß biegt sich der Pfad andersherum, sodass die Wörter dort aufrecht stehen, statt kopfüber zu hängen.",
        "Eine Kurve, eine Zeile. Der Pfad ist eine einzige kubische Kurve, und die Zeile wird von ihrer Mitte aus gesetzt, sodass das Geschriebene auf dem Bogen zentriert bleibt, wie lang die Wörter auch sind.",
        "Dieselben Wörter auf demselben Pfad, an drei Stellen begonnen: an seinem Anfang, auf halber Strecke und so, dass sie enden, wo er endet. Die Linie unter jedem ist der Pfad selbst.",
    ],
};

/// 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); 7] = [
    (Language::English, &ENGLISH),
    (Language::French, &FRENCH),
    (Language::German, &GERMAN),
    (Language::Spanish, &SPANISH),
    (Language::Italian, &ITALIAN),
    (Language::Portuguese, &PORTUGUESE),
    (Language::Dutch, &DUTCH),
];

/// 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:?}"
        );
    }
}