didbot_brand/

render.rs

//! Building the brand images: what each asset is, and painting it.

use crate::ico;
use crate::mark::{self, Lattice, Mark, Rect};
use crate::paint::{self, Cut};
use std::collections::HashMap;

/// Sites of margin left around the wordmark in the cropped logo.
pub const CROP_MARGIN: usize = 6;

/// What an asset is cropped to before it is painted.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Crop {
    /// The whole lattice — the landing page's own framing, noise and all.
    Whole,
    /// Tight to the mark, plus [`CROP_MARGIN`] sites: the logo to drop
    /// into a README or a slide, where a screenful of noise is not wanted.
    Mark,
}

/// How an asset is encoded.
#[derive(Clone, Copy)]
pub enum Format {
    /// Blocks of pixels, `scale` a site.
    Png {
        /// Output pixels a lattice site.
        scale: usize,
    },
    /// One unit a site, scaled by whoever renders it.
    Svg,
    /// A `.ico` holding one PNG an entry. Each entry names its own mark,
    /// because the ladder changes mark between 16 and 48 pixels and a
    /// favicon container spans exactly that range; the scale is whatever
    /// makes that size out of that mark's lattice.
    Ico {
        /// The container's entries, smallest first: a mark and the pixel
        /// size to paint it at.
        entries: &'static [(Mark, usize)],
    },
}

/// One file, and everything needed to make it.
pub struct Asset {
    /// Where it goes, relative to the destination root (`site/public`).
    pub path: &'static str,
    /// What is annealed to make it.
    pub mark: Mark,
    /// How much of that mark's lattice it shows.
    pub crop: Crop,
    /// Whether it is cut to a disc.
    pub cut: Cut,
    /// How it is encoded.
    pub format: Format,
}

/// Every brand image the site ships.
///
/// **This list is the brand's inventory.** Adding a size, a shape or a
/// mark is an entry here and nothing else; the builder, the `--check`
/// gate and the tests all read it.
pub const ASSETS: &[Asset] = &[
    // The logo, in the landing page's own framing: the full lattice, so
    // the wordmark sits in the field it crystallised out of.
    Asset {
        path: "brand/wordmark.png",
        mark: mark::WORDMARK,
        crop: Crop::Whole,
        cut: Cut::Square,
        format: Format::Png { scale: 4 },
    },
    Asset {
        path: "brand/wordmark.svg",
        mark: mark::WORDMARK,
        crop: Crop::Whole,
        cut: Cut::Square,
        format: Format::Svg,
    },
    // The same wordmark, cropped tight, for anywhere it has to sit beside
    // other people's logos.
    Asset {
        path: "brand/wordmark-tight.png",
        mark: mark::WORDMARK,
        crop: Crop::Mark,
        cut: Cut::Square,
        format: Format::Png { scale: 8 },
    },
    Asset {
        path: "brand/wordmark-tight.svg",
        mark: mark::WORDMARK,
        crop: Crop::Mark,
        cut: Cut::Square,
        format: Format::Svg,
    },
    // 1200x630, the size every link unfurler crops towards.
    Asset {
        path: "brand/social-card.png",
        mark: mark::BANNER,
        crop: Crop::Whole,
        cut: Cut::Square,
        format: Format::Png { scale: 6 },
    },
    // The icon, at every size a platform asks for. One mark, magnified:
    // 32 sites at one pixel a site through sixteen, so the large tiles are
    // the same picture rather than a finer one that reads busier.
    Asset {
        path: "brand/icon-512.png",
        mark: mark::BADGE,
        crop: Crop::Whole,
        cut: Cut::Square,
        format: Format::Png { scale: 8 },
    },
    Asset {
        path: "brand/icon-256.png",
        mark: mark::BADGE,
        crop: Crop::Whole,
        cut: Cut::Square,
        format: Format::Png { scale: 4 },
    },
    Asset {
        path: "brand/icon-128.png",
        mark: mark::BADGE,
        crop: Crop::Whole,
        cut: Cut::Square,
        format: Format::Png { scale: 2 },
    },
    Asset {
        path: "brand/icon-64.png",
        mark: mark::BADGE,
        crop: Crop::Whole,
        cut: Cut::Square,
        format: Format::Png { scale: 1 },
    },
    Asset {
        path: "brand/icon-48.png",
        mark: mark::BADGE_48,
        crop: Crop::Whole,
        cut: Cut::Square,
        format: Format::Png { scale: 1 },
    },
    // The two smallest tiles: the dot, because nothing with a letter in
    // it survives at sixteen sites.
    Asset {
        path: "brand/icon-32.png",
        mark: mark::DOT,
        crop: Crop::Whole,
        cut: Cut::Square,
        format: Format::Png { scale: 2 },
    },
    Asset {
        path: "brand/icon-16.png",
        mark: mark::DOT,
        crop: Crop::Whole,
        cut: Cut::Square,
        format: Format::Png { scale: 1 },
    },
    Asset {
        path: "brand/icon.svg",
        mark: mark::BADGE,
        crop: Crop::Whole,
        cut: Cut::Square,
        format: Format::Svg,
    },
    // The one icon iOS looks for by name, at the size it is happy to
    // scale down from.
    Asset {
        path: "apple-touch-icon.png",
        mark: mark::BADGE,
        crop: Crop::Whole,
        cut: Cut::Square,
        format: Format::Png { scale: 4 },
    },
    // The round cut: the same mark, corners taken away. Nothing moves,
    // because the square version already fits inside this circle — see
    // `mark::SAFE_RADIUS`.
    Asset {
        path: "brand/icon-round-512.png",
        mark: mark::BADGE,
        crop: Crop::Whole,
        cut: Cut::Round,
        format: Format::Png { scale: 8 },
    },
    Asset {
        path: "brand/icon-round-256.png",
        mark: mark::BADGE,
        crop: Crop::Whole,
        cut: Cut::Round,
        format: Format::Png { scale: 4 },
    },
    Asset {
        path: "brand/icon-round-128.png",
        mark: mark::BADGE,
        crop: Crop::Whole,
        cut: Cut::Round,
        format: Format::Png { scale: 2 },
    },
    Asset {
        path: "brand/icon-round.svg",
        mark: mark::BADGE,
        crop: Crop::Whole,
        cut: Cut::Round,
        format: Format::Svg,
    },
    // The tab icon. The badge rather than the dot, because a browser that
    // reads this file scales it to whatever the tab is and a vector of the
    // 48-site tile survives that better than any single raster — and
    // because the badge is the icon. The .ico below still carries the dot
    // for the 16 and 32 pixel entries, where blocks this small are what
    // stays legible.
    Asset {
        path: "favicon.svg",
        mark: mark::BADGE_48,
        crop: Crop::Whole,
        cut: Cut::Square,
        format: Format::Svg,
    },
    // The container a browser picks a size out of: the ladder's own three
    // small tiles, each from the mark that size is actually drawn in.
    Asset {
        path: "favicon.ico",
        mark: mark::DOT,
        crop: Crop::Whole,
        cut: Cut::Square,
        format: Format::Ico {
            entries: &[(mark::DOT, 16), (mark::DOT, 32), (mark::BADGE_48, 48)],
        },
    },
];

/// A built file: where it goes, and what goes in it.
pub struct Built {
    /// Where it goes, relative to the destination root.
    pub path: &'static str,
    /// The file's contents.
    pub bytes: Vec<u8>,
}

/// Builds every asset in [`ASSETS`].
///
/// Each distinct mark is annealed once however many assets it feeds,
/// which is most of the runtime: the wordmark's lattice alone is 35,200
/// sites through 1,200 sweeps.
pub fn build_all() -> Vec<Built> {
    let mut lattices: Lattices = HashMap::new();
    ASSETS
        .iter()
        .map(|asset| Built {
            path: asset.path,
            bytes: build_one(asset, &mut lattices),
        })
        .collect()
}

/// Annealed lattices, kept by mark name so a mark that feeds several
/// assets is annealed once. That is most of the runtime: the wordmark's
/// lattice alone is 35,200 sites through 1,200 sweeps.
pub type Lattices = HashMap<&'static str, Lattice>;

/// Builds one asset, annealing whatever marks it needs that `lattices`
/// does not already hold.
pub fn build_one(asset: &Asset, lattices: &mut Lattices) -> Vec<u8> {
    let lattice = crystallise(&asset.mark, lattices);
    let rect = match asset.crop {
        Crop::Whole => Rect {
            x: 0,
            y: 0,
            width: lattice.width,
            height: lattice.height,
        },
        Crop::Mark => Lattice::mask_bounds(
            &asset.mark.mask(),
            lattice.width,
            lattice.height,
            CROP_MARGIN,
        ),
    };
    match asset.format {
        Format::Png { scale } => paint::png(lattice, rect, scale, asset.cut),
        Format::Svg => paint::svg(lattice, rect, asset.cut).into_bytes(),
        Format::Ico { entries } => {
            let images = entries
                .iter()
                .map(|(mark, size)| {
                    let lattice = crystallise(mark, lattices);
                    let rect = Rect {
                        x: 0,
                        y: 0,
                        width: lattice.width,
                        height: lattice.height,
                    };
                    assert_eq!(
                        size % rect.width,
                        0,
                        "{size} is not a whole number of {}'s lattices",
                        mark.name
                    );
                    (
                        *size as u32,
                        paint::png(lattice, rect, size / rect.width, asset.cut),
                    )
                })
                .collect::<Vec<_>>();
            ico::ico(&images)
        }
    }
}

/// `mark`'s finished lattice, annealing it if this is the first ask.
fn crystallise<'a>(mark: &Mark, lattices: &'a mut Lattices) -> &'a Lattice {
    lattices
        .entry(mark.name)
        .or_insert_with(|| mark.crystallise())
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn no_two_assets_claim_the_same_path() {
        let mut paths: Vec<&str> = ASSETS.iter().map(|asset| asset.path).collect();
        paths.sort_unstable();
        let count = paths.len();
        paths.dedup();
        assert_eq!(paths.len(), count, "two assets write the same file");
    }

    /// A PNG asset paints whole sites, so its pixel size is a whole
    /// multiple of its lattice — this is what keeps an icon from ever
    /// being a resampled picture of a lattice rather than the lattice.
    #[test]
    fn every_raster_size_is_a_whole_number_of_sites() {
        for asset in ASSETS {
            if let Format::Ico { entries } = asset.format {
                for (mark, size) in entries {
                    assert_eq!(
                        size % mark.lattice.0,
                        0,
                        "{}: {size} is not a multiple of {}'s lattice",
                        asset.path,
                        mark.name
                    );
                }
            }
        }
    }

    /// The rule the whole icon layout is built around: an uploader that
    /// shows a square icon in a round frame crops to the tile's inscribed
    /// circle, so anything outside it is a mark some places show and
    /// others silently cut. Every icon mark — its badge *and* its specks —
    /// has to be inside that circle, which is also what lets one mark
    /// serve both cuts.
    #[test]
    fn every_icon_keeps_its_ink_inside_the_safe_circle() {
        for mark in mark::ALL
            .iter()
            .filter(|mark| mark.specks != mark::Specks::None)
        {
            let (width, height) = mark.lattice;
            let safe = width.min(height) as f32 * mark::SAFE_RADIUS;
            let centre = (width as f32 / 2.0, height as f32 / 2.0);
            for (index, lit) in mark.mask().iter().enumerate() {
                if !lit {
                    continue;
                }
                // The far corner of the site, not its centre: a site is a
                // painted block, and the crop cuts pixels rather than
                // sites.
                let (x, y) = ((index % width) as f32, (index / width) as f32);
                let dx = (x - centre.0).abs().max((x + 1.0 - centre.0).abs());
                let dy = (y - centre.1).abs().max((y + 1.0 - centre.1).abs());
                assert!(
                    (dx * dx + dy * dy).sqrt() <= safe,
                    "{}: a lit site at ({x}, {y}) is outside the safe circle",
                    mark.name
                );
            }
        }
    }

    /// The other half of what `--check` rests on. The anneal's own
    /// determinism is `mark`'s to test; this is that everything after it
    /// — the crop, the paint, the encoders — is a pure function of the
    /// lattice too, checked over every asset in the manifest from one
    /// cheap lattice rather than by annealing the real ones twice.
    #[test]
    fn encoding_an_asset_twice_writes_the_same_bytes() {
        // One shared cache across both passes, so the anneal happens once
        // per mark and what is compared is everything after it: the crop,
        // the paint and the encoders.
        let mut lattices = Lattices::new();
        for asset in ASSETS {
            let once = build_one(asset, &mut lattices);
            let again = build_one(asset, &mut lattices);
            assert_eq!(once, again, "{} is not deterministic", asset.path);
            assert!(!once.is_empty(), "{} came out empty", asset.path);
        }
    }
}