write_image_gallery.rs

//! Lays every image the tests ship with on one page, each captioned with what
//! the file itself declares.
//!
//! Nothing in the captions is written by hand: each line is read back out of
//! the image after it was parsed, so the page is a statement of what the
//! library understood rather than of what the example was told. A file that
//! declares nothing says so, which is the point of showing it next to the ones
//! that do.
//!
//! What each caption says is written in the language `HQF_PDF_LANG` names. The
//! names of the files are not, and neither is `sRGB`: both are what is written
//! on the disk and in the file.
//!
//! Usage: `cargo run --example write_image_gallery -- tmp/gallery.pdf
//! [font.ttf]`
//!        `HQF_PDF_LANG=fr cargo run --example write_image_gallery`

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

use hqf_pdf::color::icc;
use hqf_pdf::content::Content;
use hqf_pdf::cos::Name;
use hqf_pdf::{Document, Font, FontHandle, Image, ImageHandle, ImageSpace, 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 page, and the grid laid over it.
const MARGIN: f64 = 30.0;
/// See [`MARGIN`].
const COLUMNS: usize = 4;
/// See [`MARGIN`].
const ROWS: usize = 6;

/// The tallest and widest a thumbnail is drawn.
const THUMBNAIL: (f64, f64) = (110.0, 92.0);

/// The caption under each thumbnail.
const CAPTION_SIZE: f64 = 5.6;
/// See [`CAPTION_SIZE`].
const CAPTION_LEADING: f64 = 7.4;

/// Ink.
const TEXT: Rgb = Rgb::new(0.15, 0.16, 0.2);
/// See [`TEXT`].
const FADED: Rgb = Rgb::new(0.42, 0.44, 0.5);
/// See [`TEXT`].
const TILE: Rgb = Rgb::new(0.95, 0.96, 0.97);

/// Converts a count of rows, columns or lines to a float. Such counts never
/// approach the point where a `usize` loses precision as an `f64`.
#[expect(
    clippy::cast_precision_loss,
    reason = "grid and line counts are far below f64's exact-integer range"
)]
const fn count_f64(n: usize) -> f64 {
    n as f64
}

/// The name of the colour profile a file may declare it was read through. It is
/// what the profile is called, not a word of any language.
const SRGB: &str = "sRGB";

/// The name of the space a photograph its camera says it took in Adobe RGB
/// (1998) is read through, as IEC 61966-2-5 calls it.
const OPRGB: &str = "opRGB";

/// A word in its two numbers. English and French both keep the singular for one
/// and take the plural from two upwards, which is the whole of the rule the
/// captions need: a count of bits is never nought, and a table of colours never
/// holds fewer than two.
#[derive(Debug)]
struct Plural {
    one: &'static str,
    many: &'static str,
}

impl Plural {
    /// The form this word takes for `count`.
    const fn of(&self, count: usize) -> &'static str {
        if count == 1 { self.one } else { self.many }
    }
}

/// The words the captions are written in, one set per language.
#[derive(Debug)]
struct Words {
    /// What the page is called, drawn at its head.
    title: &'static str,
    /// What the document is called in what the file says of itself, which is a
    /// name rather than the sentence drawn on the page.
    file_title: &'static str,
    /// What stands between the two sides of a picture, in pixels and in dots.
    by: &'static str,
    /// What a measurement in pixels is called.
    pixels: &'static str,
    /// What a depth of one and of more than one is called.
    bits: Plural,
    /// What a resolution is called.
    dots: &'static str,
    /// What one pixel of a grey picture stands for.
    grey: &'static str,
    /// What one pixel of a three-channel picture stands for.
    rgb: &'static str,
    /// What one pixel of a four-ink picture stands for.
    cmyk: &'static str,
    /// What stands before the size of a palette.
    table_of: &'static str,
    /// What a palette holds, of one colour and of more.
    colours: Plural,
    /// What a picture in a space of none of those kinds stands for.
    other_space: &'static str,
    /// What stands before the way up a file declares.
    seen: &'static str,
    /// The ways up, in the order of the numbers a file names them by: mirrored
    /// left to right, upside down, mirrored top to bottom, mirrored and turned
    /// left, turned right, mirrored and turned right, turned left, and last the
    /// one a number nothing names falls back to.
    ways_up: [&'static str; 8],
    /// What a picture that carries an opacity for every pixel declares.
    alpha: &'static str,
    /// What a picture that drops one colour declares.
    color_key: &'static str,
    /// What stands before the name of the profile a picture was read through.
    read_through: &'static str,
    /// What a file that declares nothing beyond its shape says instead.
    nothing_else: &'static str,
}

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

/// The captions in English.
const ENGLISH: Words = Words {
    title: "Every picture the tests ship with, and what each file says about itself",
    file_title: "hqf-pdf image gallery",
    by: "by",
    pixels: "pixels",
    bits: Plural {
        one: "bit",
        many: "bits",
    },
    dots: "dots to the inch",
    grey: "grey",
    rgb: "red, green, blue",
    cmyk: "four inks",
    table_of: "a table of",
    colours: Plural {
        one: "colour",
        many: "colours",
    },
    other_space: "colours of some other kind",
    seen: "seen",
    ways_up: [
        "mirrored left to right",
        "upside down",
        "mirrored top to bottom",
        "mirrored, turned left",
        "turned right",
        "mirrored, turned right",
        "turned left",
        "the way it is stored",
    ],
    alpha: "opacity per pixel",
    color_key: "one colour left out",
    read_through: "read through",
    nothing_else: "declaring nothing else of itself",
};

/// The captions in French.
const FRENCH: Words = Words {
    title: "Toutes les images livrées avec les tests, et ce que chaque fichier dit de lui-même",
    file_title: "Galerie d’images hqf-pdf",
    by: "sur",
    pixels: "pixels",
    bits: Plural {
        one: "bit",
        many: "bits",
    },
    dots: "points par pouce",
    grey: "du gris",
    rgb: "du rouge, du vert, du bleu",
    cmyk: "quatre encres",
    table_of: "une table de",
    colours: Plural {
        one: "couleur",
        many: "couleurs",
    },
    other_space: "des couleurs d’un autre genre",
    seen: "vue",
    ways_up: [
        "en miroir gauche-droite",
        "à l’envers",
        "en miroir haut-bas",
        "en miroir, tournée à gauche",
        "tournée à droite",
        "en miroir, tournée à droite",
        "tournée à gauche",
        "telle qu’elle est stockée",
    ],
    alpha: "opacité par pixel",
    color_key: "une couleur laissée de côté",
    read_through: "lue à travers",
    nothing_else: "ne déclarant rien d’autre",
};

/// The captions in Dutch.
const DUTCH: Words = Words {
    title: "Elke afbeelding die bij de tests hoort, en wat elk bestand over zichzelf zegt",
    file_title: "Afbeeldingengalerij van hqf-pdf",
    by: "bij",
    pixels: "pixels",
    bits: Plural {
        one: "bit",
        many: "bits",
    },
    dots: "punten per inch",
    grey: "grijs",
    rgb: "rood, groen, blauw",
    cmyk: "vier inkten",
    table_of: "een tabel van",
    colours: Plural {
        one: "kleur",
        many: "kleuren",
    },
    other_space: "kleuren van een andere soort",
    seen: "gezien",
    ways_up: [
        "links-rechts gespiegeld",
        "ondersteboven",
        "boven-onder gespiegeld",
        "gespiegeld, naar links gedraaid",
        "naar rechts gedraaid",
        "gespiegeld, naar rechts gedraaid",
        "naar links gedraaid",
        "zoals ze is opgeslagen",
    ],
    alpha: "dekking per pixel",
    color_key: "één kleur weggelaten",
    read_through: "gelezen via",
    nothing_else: "zonder verder iets over zichzelf te zeggen",
};

/// The captions in Portuguese.
const PORTUGUESE: Words = Words {
    title: "Cada imagem que acompanha os testes, e o que cada ficheiro diz de si mesmo",
    file_title: "Galeria de imagens do hqf-pdf",
    by: "por",
    pixels: "píxeis",
    bits: Plural {
        one: "bit",
        many: "bits",
    },
    dots: "pontos por polegada",
    grey: "cinzento",
    rgb: "vermelho, verde, azul",
    cmyk: "quatro tintas",
    table_of: "uma tabela de",
    colours: Plural {
        one: "cor",
        many: "cores",
    },
    other_space: "cores de outro tipo",
    seen: "vista",
    ways_up: [
        "espelhada da esquerda para a direita",
        "de pernas para o ar",
        "espelhada de cima para baixo",
        "espelhada, rodada para a esquerda",
        "rodada para a direita",
        "espelhada, rodada para a direita",
        "rodada para a esquerda",
        "tal como está guardada",
    ],
    alpha: "opacidade por píxel",
    color_key: "uma cor excluída",
    read_through: "lida através de",
    nothing_else: "sem declarar mais nada de si",
};

/// The captions in Italian.
const ITALIAN: Words = Words {
    title: "Ogni immagine fornita con i test, e ciò che ogni file dice di sé",
    file_title: "Galleria di immagini di hqf-pdf",
    by: "per",
    pixels: "pixels",
    bits: Plural {
        one: "bit",
        many: "bits",
    },
    dots: "punti per pollice",
    grey: "grigio",
    rgb: "rosso, verde, blu",
    cmyk: "quattro inchiostri",
    table_of: "una tabella di",
    colours: Plural {
        one: "colore",
        many: "colori",
    },
    other_space: "colori di altro tipo",
    seen: "vista",
    ways_up: [
        "specchiata da sinistra a destra",
        "capovolta",
        "specchiata dall’alto in basso",
        "specchiata, ruotata a sinistra",
        "ruotata a destra",
        "specchiata, ruotata a destra",
        "ruotata a sinistra",
        "com’è memorizzata",
    ],
    alpha: "opacità per pixel",
    color_key: "un colore escluso",
    read_through: "letta tramite",
    nothing_else: "senza dichiarare altro di sé",
};

/// The captions in Spanish.
const SPANISH: Words = Words {
    title: "Cada imagen que traen las pruebas, y lo que cada archivo dice de sí mismo",
    file_title: "Galería de imágenes de hqf-pdf",
    by: "por",
    pixels: "píxeles",
    bits: Plural {
        one: "bit",
        many: "bits",
    },
    dots: "puntos por pulgada",
    grey: "gris",
    rgb: "rojo, verde, azul",
    cmyk: "cuatro tintas",
    table_of: "una tabla de",
    colours: Plural {
        one: "color",
        many: "colores",
    },
    other_space: "colores de otro tipo",
    seen: "vista",
    ways_up: [
        "reflejada de izquierda a derecha",
        "cabeza abajo",
        "reflejada de arriba abajo",
        "reflejada, girada a la izquierda",
        "girada a la derecha",
        "reflejada, girada a la derecha",
        "girada a la izquierda",
        "tal como está guardada",
    ],
    alpha: "opacidad por píxel",
    color_key: "un color excluido",
    read_through: "leída mediante",
    nothing_else: "sin declarar nada más de sí misma",
};

/// The captions in German.
const GERMAN: Words = Words {
    title: "Jedes Bild, das die Tests mitbringen, und was jede Datei über sich sagt",
    file_title: "hqf-pdf-Bildergalerie",
    by: "mal",
    pixels: "Pixel",
    bits: Plural {
        one: "Bit",
        many: "Bit",
    },
    dots: "Punkte pro Zoll",
    grey: "Grau",
    rgb: "Rot, Grün, Blau",
    cmyk: "vier Farben",
    table_of: "eine Tabelle mit",
    colours: Plural {
        one: "Farbe",
        many: "Farben",
    },
    other_space: "Farben anderer Art",
    seen: "Ansicht:",
    ways_up: [
        "von links nach rechts gespiegelt",
        "auf dem Kopf",
        "von oben nach unten gespiegelt",
        "gespiegelt, nach links gedreht",
        "nach rechts gedreht",
        "gespiegelt, nach rechts gedreht",
        "nach links gedreht",
        "so, wie es gespeichert ist",
    ],
    alpha: "Deckkraft je Pixel",
    color_key: "eine Farbe ausgespart",
    read_through: "gelesen über",
    nothing_else: "gibt sonst nichts über sich an",
};

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

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

/// Every image committed for the tests, in the order their names sort.
fn corpus() -> Result<Vec<PathBuf>, std::io::Error> {
    let images = Path::new(env!("CARGO_MANIFEST_DIR"))
        .join("tests")
        .join("images");

    let mut paths: Vec<PathBuf> = fs::read_dir(images)?
        .filter_map(|entry| entry.ok().map(|entry| entry.path()))
        .filter(|path| path.is_file())
        .collect();
    paths.sort();
    Ok(paths)
}

/// What one pixel of the image stands for, in the fewest words that still say
/// it.
fn colour_of(image: &Image, words: &'static Words) -> String {
    match image.color_space() {
        ImageSpace::Gray => words.grey.to_owned(),
        ImageSpace::Rgb => words.rgb.to_owned(),
        ImageSpace::Cmyk => words.cmyk.to_owned(),
        ImageSpace::Indexed(palette) => {
            let colours = palette.len() / 3;
            format!("{} {colours} {}", words.table_of, words.colours.of(colours))
        }
        _ => words.other_space.to_owned(),
    }
}

/// What the file says about itself, one statement at a time.
///
/// A file that says nothing beyond its shape says so: the point of the page is
/// that both kinds sit side by side.
fn facts(image: &Image, words: &'static Words) -> Vec<String> {
    let bits = usize::from(image.bits_per_component());
    let mut facts = vec![
        format!(
            "{} {} {} {}",
            image.width(),
            words.by,
            image.height(),
            words.pixels
        ),
        colour_of(image, words),
        format!("{bits} {}", words.bits.of(bits)),
    ];

    let mut stated: Vec<String> = Vec::new();
    if let Some(resolution) = image.resolution() {
        stated.push(format!(
            "{:.0} {} {:.0} {}",
            resolution.x(),
            words.by,
            resolution.y(),
            words.dots
        ));
    }
    if let Some(orientation) = image.orientation() {
        stated.push(format!(
            "{} {}",
            words.seen,
            way_up(words, orientation.tag())
        ));
    }
    if image.has_alpha() {
        stated.push(words.alpha.to_owned());
    }
    if image.color_key().is_some() {
        stated.push(words.color_key.to_owned());
    }
    if let Some(profile) = image.icc_profile() {
        let space = if profile == icc::adobe_rgb().as_slice() {
            OPRGB
        } else {
            SRGB
        };
        stated.push(format!("{} {space}", words.read_through));
    }

    if stated.is_empty() {
        facts.push(words.nothing_else.to_owned());
    } else {
        facts.extend(stated);
    }
    facts
}

/// The statements laid end to end, broken into lines that fit `width`.
///
/// Nothing is dropped: a caption that will not fit on one line takes as many as
/// it needs, which is what keeps the page a full account of what was read.
fn packed(font: &FontHandle, width: f64, facts: &[String]) -> Vec<String> {
    let mut lines: Vec<String> = Vec::new();
    for fact in facts {
        match lines.last_mut() {
            Some(line) if font.measure(&format!("{line}, {fact}"), CAPTION_SIZE) <= width => {
                line.push_str(", ");
                line.push_str(fact);
            }
            _ => lines.push(fact.clone()),
        }
    }
    lines
}

/// The way up an `Exif` header names by its number, in words. A number nothing
/// names falls to the last of them.
const fn way_up(words: &'static Words, tag: u16) -> &'static str {
    match tag {
        2..=8 => words.ways_up[(tag - 2) as usize],
        _ => words.ways_up[7],
    }
}

/// Draws one line of text, left-aligned.
fn text(content: &mut Content, font: &FontHandle, size: f64, x: f64, y: f64, colour: Rgb, s: &str) {
    let _ = content.set_fill(colour);
    content.begin_text();
    let _ = content.set_font(font, size);
    let _ = content.text_origin(x, y);
    content.show_glyphs(&font.glyphs(s));
    content.end_text();
}

/// Draws one line of text, shortened until it fits the width it is given.
fn text_fitted(
    content: &mut Content,
    font: &FontHandle,
    size: f64,
    at: (f64, f64),
    width: f64,
    colour: Rgb,
    s: &str,
) {
    let mut line = s.to_owned();
    while font.measure(&line, size) > width && line.chars().count() > 1 {
        line.pop();
        line.pop();
        line.push('…');
    }
    text(content, font, size, at.0, at.1, colour, &line);
}

/// Draws one tile: the picture inside its box, and what the file says under it.
fn tile(
    content: &mut Content,
    font: &FontHandle,
    handle: &ImageHandle,
    lines: &[String],
    at: (f64, f64),
    cell: (f64, f64),
) -> Result<(), Box<dyn std::error::Error>> {
    let (x, y) = at;
    let (cell_width, cell_height) = cell;
    let caption_height = CAPTION_LEADING * count_f64(lines.len());
    let box_height = cell_height - caption_height - 6.0;

    content.set_fill(TILE)?;
    content.rect(x, y + caption_height + 6.0, cell_width, box_height)?;
    content.fill();

    // The picture keeps its proportions inside the box, and sits in the middle
    // of it.
    let (width, height) = handle.fit_within(
        THUMBNAIL.0.min(cell_width - 8.0),
        THUMBNAIL.1.min(box_height),
    )?;
    content.draw_image(
        handle,
        x + (cell_width - width) / 2.0,
        y + caption_height + 6.0 + (box_height - height) / 2.0,
        width,
        height,
    )?;

    for (index, line) in lines.iter().enumerate() {
        let colour = if index == 0 { TEXT } else { FADED };
        text_fitted(
            content,
            font,
            CAPTION_SIZE,
            (
                x,
                CAPTION_LEADING.mul_add(-count_f64(index + 1), y + caption_height) + 2.0,
            ),
            cell_width,
            colour,
            line,
        );
    }
    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);

    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("image_gallery")));
    let font_path = args.next().map_or_else(default_font, PathBuf::from);

    let mut doc = Document::new();
    doc.set_license(licence::licensed());
    doc.set_info(Name::new("Title"), words.file_title);
    let font = doc.add_font(Font::parse(fs::read(&font_path)?)?);

    let page = Page::a4();
    let (page_width, page_height) = (page.width, page.height);
    let cell_width = 2.0_f64.mul_add(-MARGIN, page_width) / count_f64(COLUMNS) - 6.0;

    let paths = corpus()?;
    let mut tiles = Vec::new();
    for path in &paths {
        let image = Image::parse(fs::read(path)?)?;
        let mut lines = vec![
            path.file_name()
                .unwrap_or_default()
                .to_string_lossy()
                .into_owned(),
        ];
        lines.extend(packed(&font, cell_width, &facts(&image, words)));
        tiles.push((doc.add_image(image), lines));
    }

    let mut content = Content::new();

    text(
        &mut content,
        &font,
        13.0,
        MARGIN,
        page_height - MARGIN - 10.0,
        TEXT,
        words.title,
    );

    let top = page_height - MARGIN - 34.0;
    let cell_height = (top - MARGIN) / count_f64(ROWS);

    for (index, (handle, lines)) in tiles.iter().enumerate() {
        let column = index % COLUMNS;
        let row = index / COLUMNS;
        if row >= ROWS {
            println!(
                "{} pictures do not fit on one page; the rest are left off",
                tiles.len()
            );
            break;
        }

        tile(
            &mut content,
            &font,
            handle,
            lines,
            (
                (cell_width + 6.0).mul_add(count_f64(column), MARGIN),
                top - cell_height * count_f64(row + 1),
            ),
            (cell_width, cell_height - 6.0),
        )?;
    }

    let mut page = page;
    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, {} pictures",
        bytes.len(),
        tiles.len()
    );
    Ok(())
}

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

    use super::{
        CAPTION_SIZE, COLUMNS, MARGIN, ROWS, WORDS, corpus, count_f64, default_font, facts,
        language,
    };

    /// A4, in points, which is the sheet the gallery is laid on.
    const PAGE: (f64, f64) = (595.276, 841.890);

    /// The lines two languages are allowed to write the same way. Both call a
    /// pixel a pixel, and both spell a bit and its plural the same.
    const SPARED: [&str; 6] = [
        "pixels: \"pixels\"",
        "one: \"bit\"",
        "many: \"bits\"",
        // Written the same way in Italian.
        r#"seen: "vista""#,
        // Written the same way in Portuguese.
        r#""tal como está guardada""#,
        r#"by: "por""#,
    ];

    /// The font every measurement here is taken in, which is the one the
    /// example draws with when the command line says nothing.
    fn font(document: &mut Document) -> FontHandle {
        document.add_font(
            Font::parse(std::fs::read(default_font()).expect("the committed font is there"))
                .expect("the committed font parses"),
        )
    }

    /// The width of one tile, worked out the way the page works it out.
    fn cell_width() -> f64 {
        2.0_f64.mul_add(-MARGIN, PAGE.0) / count_f64(COLUMNS) - 6.0
    }

    /// The page shows every picture the tests ship with, and it says so; a
    /// picture past the last cell of the grid is left off with a line on the
    /// terminal and nothing on the page.
    #[test]
    fn the_grid_holds_every_picture_the_tests_ship_with() {
        let held = corpus().expect("the committed images are there").len();

        assert!(
            held <= COLUMNS * ROWS,
            "the tests ship {held} pictures and the grid holds {}",
            COLUMNS * ROWS
        );
    }

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

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

    /// A line wider than its tile is shortened until it fits, and the end of it
    /// is replaced by a single character. The page is meant to be a full
    /// account of what was read, so no statement may be one that has to be cut:
    /// a language whose words run longer has to find shorter ones.
    #[test]
    fn no_language_states_a_fact_too_wide_to_be_read_whole() {
        let mut document = Document::new();
        let font = font(&mut document);
        let width = cell_width();

        for (named, words) in WORDS {
            for path in corpus().expect("the committed images are there") {
                let image =
                    Image::parse(std::fs::read(&path).expect("a committed image is readable"))
                        .expect("a committed image parses");

                for fact in facts(&image, words) {
                    let measured = font.measure(&fact, CAPTION_SIZE);

                    assert!(
                        measured <= width,
                        "the {} caption of {} states {fact:?} over {measured:.1} \
                         points, and a tile is {width:.1} wide",
                        named.code(),
                        path.display()
                    );
                }
            }
        }
    }
}