Colour the document defines

//! Colour the document defines, next to colour it leaves to the device.
//!
//! `0.2 0.4 0.8 rg` says three numbers and leaves what they look like to
//! whatever shows them. The rows below say colour two other ways: through the
//! ICC profile the file carries, so the numbers mean what they meant when the
//! document was made, and as CIE 1976 L*a*b*, where lightness and colour are
//! separate numbers by construction.
//!
//! What the page reads is held in `Words`, once per language, and
//! `HQF_PDF_LANG` picks which set is drawn. The numbers the swatches are
//! painted from are not language: they are the same colours whoever reads the
//! page.
//!
//! Usage: `cargo run --example write_measured_color -- tmp/measured.pdf
//! [font.ttf]`
//!        `HQF_PDF_LANG=fr cargo run --example write_measured_color --
//! tmp/mesuree.pdf`

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

use hqf_pdf::color::icc;
use hqf_pdf::content::Content;
use hqf_pdf::{
    ColorSpaceHandle, DeviceSpace, Document, Font, FontHandle, IccBased, Lab, Page, Rgb,
};

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

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

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

use language::Language;

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

/// The size of one swatch, in points.
const SWATCH: (f64, f64) = (70.0, 60.0);

/// The left edge of the first swatch.
const LEFT: f64 = 70.0;

/// The left edge of each swatch in a row: the first one, then every
/// seventy-eight points across.
const COLUMN_X: &[f64] = &[70.0, 148.0, 226.0, 304.0, 382.0, 460.0];

/// The six colours the first two rows are painted in, as three numbers each.
const COLORS: &[[f64; 3]] = &[
    [0.85, 0.20, 0.15],
    [0.92, 0.58, 0.10],
    [0.20, 0.55, 0.30],
    [0.12, 0.40, 0.70],
    [0.45, 0.25, 0.60],
    [0.20, 0.20, 0.22],
];

/// Six lightnesses at one colour, as `L*`, `a*` and `b*`.
const LIGHTNESSES: &[[f64; 3]] = &[
    [20.0, 40.0, 25.0],
    [35.0, 40.0, 25.0],
    [50.0, 40.0, 25.0],
    [65.0, 40.0, 25.0],
    [80.0, 40.0, 25.0],
    [95.0, 40.0, 25.0],
];

/// Six colours at one lightness, as `L*`, `a*` and `b*`.
const HUES: &[[f64; 3]] = &[
    [60.0, 60.0, 40.0],
    [60.0, 20.0, 60.0],
    [60.0, -50.0, 45.0],
    [60.0, -40.0, -20.0],
    [60.0, 10.0, -55.0],
    [60.0, 50.0, -20.0],
];

/// The words the page is written in, one set per language.
///
/// The numbers the swatches are painted from are not here: three numbers are
/// the same three numbers in every language.
#[derive(Debug)]
struct Words {
    /// The line at the head of the page.
    title: &'static str,
    /// The two lines under it, saying what the first two rows hold.
    intro: [&'static str; 2],
    /// What each row of swatches shows, in the order the rows are drawn.
    rows: [&'static str; 4],
    /// The line under the stroked rule.
    rule: &'static str,
    /// The three lines at the foot of the page.
    closing: [&'static str; 3],
}

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: "Colour the document defines, not the device",
    intro: [
        "The first two rows hold the same six sets of three numbers. The second row names a colour",
        "space the file carries the profile for, so what those numbers mean travels with the file.",
    ],
    rows: [
        "Three numbers said as they are, left to whatever shows them",
        "The same three numbers, read through the sRGB profile the file carries",
        "One colour at six lightnesses, said as L*a*b*: only the first number changes",
        "Six colours at one lightness: only the other two change",
    ],
    rule: "A rule stroked in the same space, by the stroking operators",
    closing: [
        "The first two rows look alike on a screen that is already sRGB, and that is the point:",
        "the difference is not what they look like here. It is that the second row still names these",
        "colours on a press, on another screen, and in ten years, because the file says what it means.",
    ],
};

/// The page in French.
const FRENCH: Words = Words {
    title: "La couleur que le document définit, pas celle de l'appareil",
    intro: [
        "Les deux premières rangées portent les mêmes six jeux de trois nombres. La seconde",
        "nomme un espace dont le fichier porte le profil : ces nombres gardent leur sens partout.",
    ],
    rows: [
        "Trois nombres dits tels quels, laissés à ce qui les affiche",
        "Les mêmes trois nombres, lus à travers le profil sRGB que porte le fichier",
        "Une couleur à six clartés, dite en L*a*b* : seul le premier nombre change",
        "Six couleurs à une même clarté : seuls les deux autres changent",
    ],
    rule: "Un filet tracé dans le même espace, par les opérateurs de trait",
    closing: [
        "Les deux premières rangées se ressemblent sur un écran déjà sRGB, et c'est bien le point :",
        "la différence n'est pas dans ce qu'on voit ici. C'est que la seconde rangée nomme encore",
        "ces couleurs sur une presse, sur un autre écran et dans dix ans, car le fichier le dit.",
    ],
};

/// 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)];

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

/// Draws a row of swatches, each painted by `paint`, and captions it.
fn row(
    content: &mut Content,
    font: &FontHandle,
    y: f64,
    caption: &str,
    count: usize,
    mut paint: impl FnMut(&mut Content, usize) -> Result<(), hqf_pdf::Error>,
) -> Result<(), hqf_pdf::Error> {
    let (width, height) = SWATCH;

    for (column, x) in COLUMN_X.iter().enumerate().take(count) {
        content.save_state();
        paint(content, column)?;
        content.rect(*x, y, width, height)?.fill();
        content.restore_state();
    }

    content.save_state();
    content.set_fill(Rgb::gray(0.35))?;
    text(content, font, 9.0, LEFT, y - 14.0, caption)?;
    content.restore_state();
    Ok(())
}

/// Draws the four rows of swatches.
fn rows(
    content: &mut Content,
    font: &FontHandle,
    words: &Words,
    profile: &ColorSpaceHandle,
    lab: &ColorSpaceHandle,
) -> Result<(), hqf_pdf::Error> {
    row(
        content,
        font,
        660.0,
        words.rows[0],
        COLORS.len(),
        |content, column| {
            let [r, g, b] = COLORS[column];
            content.set_fill(Rgb::new(r, g, b))?;
            Ok(())
        },
    )?;

    row(
        content,
        font,
        560.0,
        words.rows[1],
        COLORS.len(),
        |content, column| {
            content.set_fill_space(profile);
            content.set_fill_components(&COLORS[column])?;
            Ok(())
        },
    )?;

    row(
        content,
        font,
        460.0,
        words.rows[2],
        LIGHTNESSES.len(),
        |content, column| {
            content.set_fill_space(lab);
            content.set_fill_components(&LIGHTNESSES[column])?;
            Ok(())
        },
    )?;

    row(
        content,
        font,
        360.0,
        words.rows[3],
        HUES.len(),
        |content, column| {
            content.set_fill_space(lab);
            content.set_fill_components(&HUES[column])?;
            Ok(())
        },
    )
}

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

    let mut args = env::args().skip(1);
    // 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 = args
        .next()
        .unwrap_or_else(|| language.file_name(&out::default_path("measured")));
    let font_path = args.next().map_or_else(default_font, PathBuf::from);

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

    let profile = doc.add_color_space(IccBased::new(&icc::srgb(), DeviceSpace::Rgb)?);
    // The white of D65 daylight, as CIE XYZ: the light L*a*b* is measured
    // against here.
    let lab =
        doc.add_color_space(Lab::new([0.9505, 1.0, 1.089]).range([-100.0, 100.0, -100.0, 100.0]));

    let mut content = Content::new();
    text(&mut content, &font, 15.0, LEFT, 780.0, words.title)?;
    content.save_state();
    content.set_fill(Rgb::gray(0.35))?;
    text(&mut content, &font, 10.0, LEFT, 762.0, words.intro[0])?;
    text(&mut content, &font, 10.0, LEFT, 748.0, words.intro[1])?;
    content.restore_state();

    rows(&mut content, &font, words, &profile, &lab)?;

    // A stroke is said in its own space, by its own operators.
    content.save_state();
    content.set_stroke_space(&lab);
    content.set_stroke_components(&[45.0, 55.0, 35.0])?;
    content.set_line_width(6.0)?;
    content.move_to(LEFT, 300.0)?;
    content.line_to(COLUMN_X[COLORS.len() - 1] + SWATCH.0, 300.0)?;
    content.stroke();
    content.restore_state();

    content.save_state();
    content.set_fill(Rgb::gray(0.35))?;
    text(&mut content, &font, 9.0, LEFT, 280.0, words.rule)?;
    content.restore_state();

    content.save_state();
    content.set_fill(Rgb::gray(0.25))?;
    for (y, line) in [235.0, 221.0, 207.0].into_iter().zip(words.closing) {
        text(&mut content, &font, 10.0, LEFT, y, line)?;
    }
    content.restore_state();

    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, {} swatches in two spaces the document defines",
        bytes.len(),
        COLORS.len() * 3
    );
    Ok(())
}

#[cfg(test)]
mod tests {
    use hqf_pdf::{Document, Font};

    use super::{COLORS, COLUMN_X, LEFT, SWATCH, WORDS, default_font, language};

    /// The lines two languages are allowed to write the same way. Every line
    /// here is a sentence or a caption, and no two languages write one alike.
    const SPARED: [&str; 0] = [];

    /// The gap between one swatch and the next.
    const GUTTER: f64 = COLUMN_X[1] - COLUMN_X[0] - SWATCH.0;

    /// The room a line has: the page is laid out around its rows of swatches,
    /// and a line may reach the end of a row and the gap that follows it.
    const MEASURE: f64 = COLUMN_X[COLORS.len() - 1] + SWATCH.0 + GUTTER - LEFT;

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

    /// Nothing on the page is broken to a width: a line longer than the row of
    /// swatches it explains runs out past them and towards the paper's edge.
    #[test]
    fn every_language_writes_lines_no_wider_than_the_swatches_they_explain() {
        let mut doc = Document::new();
        let font = Font::parse(std::fs::read(default_font()).expect("the committed font is there"))
            .expect("the committed font parses");
        let text = doc.add_font(font);

        for (named, words) in WORDS {
            let code = named.code();
            let lines = [(15.0, words.title), (9.0, words.rule)]
                .into_iter()
                .chain(words.intro.map(|line| (10.0, line)))
                .chain(words.rows.map(|line| (9.0, line)))
                .chain(words.closing.map(|line| (10.0, line)));

            for (size, line) in lines {
                let measured = text.measure(line, size);
                assert!(
                    measured <= MEASURE,
                    "the {code} page draws {line:?} over {measured:.1} points, \
                     and the swatches under it run {MEASURE:.1}"
                );
            }
        }
    }
}