didbot_brand/

mark.rs

//! What gets crystallised, and the snap of the simulation that does it.
//!
//! A mark is a shape for the external field to pull the lattice towards —
//! the "did.bot" wordmark for the logo, a "d" cut out of a disc for the
//! icons, a plain disc for the tiles too small to hold a letter — plus
//! the lattice size and RNG seed that together make one particular run of
//! the anneal. Given those, the finished lattice is a pure function: the
//! same mark always crystallises into the same spins.

use didbot_site_anim::anneal::{run_full_anneal_pinned, AnnealSchedule, DEFAULT_TOTAL_SWEEPS};
use didbot_site_anim::ising::{didbot_mask, text_mask};

/// What shape the field pulls the lattice towards.
///
/// A size ladder rather than a set of alternatives: the wordmark is the
/// logo, the knockout is the icon, and the disc is what is left when a
/// tile is sixteen pixels across. [`Shape::Text`] sets the font for
/// whatever a knockout cuts.
#[derive(Clone, Copy)]
pub enum Shape {
    /// The "did.bot" wordmark, laid out the way the landing page lays it
    /// out — hung off its own "." rather than centred — rather than as
    /// text this crate composed.
    Wordmark,
    /// Lines of the same six-glyph font, centred as a lockup. No mark
    /// ships as one today; it is what [`Shape::Knockout`] cuts with, and
    /// what a second line would be set in if the icons ever wanted one.
    Text(&'static [&'static str]),
    /// A filled disc. Letterforms do not survive this anneal below about
    /// three lattice sites to the glyph pixel — surface tension closes a
    /// two-site counter, and a "d" comes out a blob — so the smallest
    /// tile gets the one shape a lattice this coarse can still hold, and
    /// the one the dynamics actively help: a single ordered domain, which
    /// is also the "." in did.bot.
    Disc,
    /// A disc with `lines` cut out of it: the letterform is the ground
    /// showing through, not the ink.
    ///
    /// This is what every icon above the dot is. A letter
    /// set *positively* at 32 sites is a stroke of ink two or three sites
    /// wide with noise on both flanks; cut out of a disc instead, both
    /// its flanks are one large ordered domain, which is far more stable
    /// — the shape is carried by an edge rather than by a thin ribbon.
    /// The counter still has to be a hole several sites across, which is
    /// why `glyph` is well under [`Mark::fill`] rather than filling it.
    Knockout {
        /// The lines to cut, in this crate's own six-glyph font.
        lines: &'static [&'static str],
        /// How much of the tile the letterform spans, as a fraction.
        glyph: f32,
    },
}

/// Whether a mark carries the signature specks.
///
/// Three lit sites the field does not decide: two up by the top corners,
/// one below. They are not decoration added to a finished picture — each
/// is a *pinned* site ([`didbot_site_anim::ising::IsingModel::pin_spin`])
/// with a small island of field around it, so the lattice grows whatever
/// shape it likes on them. At 16 sites that is a single pixel, the way
/// they first came out of the anneal; on a bigger tile the island is
/// bigger and the anneal makes it irregular, which is the point — three
/// identical squares would read as a stamp.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub enum Specks {
    /// None: the wordmark and the social card are all field already.
    None,
    /// The three, in the ring between the mark and the safe circle.
    Three,
}

/// The three specks' directions from the centre, taken from where the
/// first anneal happened to leave them on the 16-site tile, as unit-ish
/// vectors in screen coordinates (y down).
const SPECK_DIRECTIONS: [(f32, f32); 3] = [(-0.81, -0.59), (0.76, -0.65), (0.07, 1.0)];
/// How far out the specks sit, as a fraction of the tile's width.
///
/// The ring they live in is narrow and both its edges are hard: outside
/// [`SAFE_RADIUS`] an uploader's round crop cuts them off, and inside the
/// badge's own edge they stop being separate dots and merge with it. This
/// is the middle of what is left, which is also why the badge is not
/// larger than it is.
const SPECK_ORBIT: f32 = 0.395;
/// A speck's field island, as a fraction of the tile.
const SPECK_RADIUS: f32 = 0.04;

/// Everything an icon draws stays inside this radius, as a fraction of
/// the tile's width — the tile's own inscribed circle, less a hair.
///
/// Not a stylistic margin: uploaders that show a square icon in a round
/// frame crop to exactly this circle, so anything outside it is a mark
/// that some places show and others silently cut. One layout satisfies
/// both frames, which is why a round icon here is the same mark as the
/// square one with a different [`crate::paint::Cut`] rather than a mark of
/// its own.
pub const SAFE_RADIUS: f32 = 0.49;

/// One mark: a shape, the lattice it is annealed on, and the seed.
#[derive(Clone, Copy)]
pub struct Mark {
    /// Appears in the manifest and in test failures; kebab-case.
    pub name: &'static str,
    /// What the field aims at.
    pub shape: Shape,
    /// The three pinned specks, or [`Specks::None`].
    pub specks: Specks,
    /// How much of the lattice the mark fills, as a fraction of the
    /// binding axis — its diameter, for a [`Shape::Disc`]. Lower for
    /// round marks, which have to clear a circle.
    pub fill: f32,
    /// Lattice size in sites. This is the grain of the noise: an icon
    /// painted a block a site reads as the same material as the landing
    /// page, whatever the tile it ends up in, because the blocks are the
    /// page's own — bigger on screen, never resampled.
    pub lattice: (usize, usize),
    /// The RNG seed: which run of the anneal this is. Always one of the
    /// twelve `anneal.rs`'s crystallisation property test measures, so
    /// the run behind a shipped image is one the test suite has actually
    /// seen — and, for everything but the wordmark, the one of those
    /// twelve that came out cleanest, since a seed is a free choice and
    /// there is no reason to ship a worse frame than the schedule can
    /// give. [`WORDMARK`] keeps the landing page's own seed instead
    /// (`site/src/config/anim.ts`), because a logo that is not the frame
    /// the page ends on would be a different picture wearing the same
    /// name; [`BANNER`] cannot be that frame anyway — its lattice is a
    /// different shape — so it is free to take the cleanest run too.
    pub seed: u32,
}

/// The landing page's own lattice: 220x160, seed 11 — the numbers in
/// `site/src/config/anim.ts`, which is why this image and the page agree.
pub const WORDMARK: Mark = Mark {
    name: "wordmark",
    shape: Shape::Wordmark,
    specks: Specks::None,
    fill: 0.0, // unused: the wordmark's own layout decides
    lattice: (220, 160),
    seed: 11,
};

/// The wordmark again on a wider, shorter lattice, for the social card:
/// 200x105 is what 1200x630 divides into at six pixels a site.
pub const BANNER: Mark = Mark {
    name: "banner",
    shape: Shape::Wordmark,
    specks: Specks::None,
    fill: 0.0,
    lattice: (200, 105),
    seed: 909,
};

/// The icon: a "d" cut out of a disc, with the three specks in the ring
/// around it — one mark for every tile from 64 pixels up, painted square
/// or round from the same lattice, since the square version already fits
/// inside the circle a round frame crops to (see [`SAFE_RADIUS`]).
///
/// Sixty-four sites, and the big tiles are this magnified rather than a
/// finer lattice of their own. A finer lattice is not the same icon: the
/// stray lit sites the anneal leaves scale with the site count, so at 128
/// or 256 sites the background fills with dust and the thing reads busy
/// instead of as one shape.
pub const BADGE: Mark = Mark {
    name: "badge",
    shape: Shape::Knockout {
        lines: &["d"],
        glyph: 0.50,
    },
    specks: Specks::Three,
    fill: 0.68,
    lattice: (64, 64),
    seed: 202,
};

/// [`BADGE`] on the 48-site tile: the same proportions, for the one size
/// that is not a whole multiple of 64.
pub const BADGE_48: Mark = Mark {
    name: "badge-48",
    shape: Shape::Knockout {
        lines: &["d"],
        glyph: 0.50,
    },
    specks: Specks::Three,
    fill: 0.68,
    lattice: (48, 48),
    seed: 2,
};

/// The bottom of the ladder: the dot, on a lattice of its own, painted at
/// one and two pixels a site for the 16 and 32 pixel tiles.
///
/// Sixteen sites hold no letterform at all — not two lines of three
/// glyphs, not one glyph, and not a knockout either, since a hole needs
/// sites too and a "d" cut small enough to leave the specks their ring
/// has a two-site stroke. See [`Shape::Disc`].
pub const DOT: Mark = Mark {
    name: "dot",
    shape: Shape::Disc,
    specks: Specks::Three,
    fill: 0.66,
    lattice: (16, 16),
    seed: 2,
};

/// Every mark, for the tests that hold all of them to the same bar.
pub const ALL: &[Mark] = &[WORDMARK, BANNER, BADGE, BADGE_48, DOT];

impl Mark {
    /// The shape the field pulls towards, as a bitmap on this mark's
    /// lattice, specks included.
    pub fn mask(&self) -> Vec<bool> {
        let (width, height) = self.lattice;
        let mut mask = match self.shape {
            Shape::Wordmark => didbot_mask(width, height),
            Shape::Text(lines) => text_mask(lines, width, height, self.fill),
            Shape::Disc => self.disc(self.fill),
            Shape::Knockout { lines, glyph } => {
                let letter = text_mask(lines, width, height, glyph);
                self.disc(self.fill)
                    .iter()
                    .zip(&letter)
                    .map(|(lit, cut)| *lit && !*cut)
                    .collect()
            }
        };
        let radius = width.min(height) as f32 * SPECK_RADIUS;
        for (x, y) in self.speck_sites() {
            paint_disc(
                &mut mask,
                (width, height),
                (x as f32 + 0.5, y as f32 + 0.5),
                radius,
            );
        }
        mask
    }

    /// A disc of `fill` of the tile, centred — the ground a [`Shape::Disc`]
    /// is and a [`Shape::Knockout`] cuts into.
    fn disc(&self, fill: f32) -> Vec<bool> {
        let (width, height) = self.lattice;
        let mut mask = vec![false; width * height];
        paint_disc(
            &mut mask,
            (width, height),
            (width as f32 / 2.0, height as f32 / 2.0),
            width.min(height) as f32 * fill / 2.0,
        );
        mask
    }

    /// The sites this mark pins up-spin: its specks' centres, and nothing
    /// else. Empty for [`Specks::None`].
    pub fn speck_sites(&self) -> Vec<(usize, usize)> {
        if self.specks == Specks::None {
            return Vec::new();
        }
        let (width, height) = self.lattice;
        let span = width.min(height) as f32;
        let centre = (width as f32 / 2.0, height as f32 / 2.0);
        SPECK_DIRECTIONS
            .iter()
            .map(|(dx, dy)| {
                let x = centre.0 + dx * span * SPECK_ORBIT;
                let y = centre.1 + dy * span * SPECK_ORBIT;
                (
                    (x.max(0.0) as usize).min(width - 1),
                    (y.max(0.0) as usize).min(height - 1),
                )
            })
            .collect()
    }

    /// Runs the shipped anneal to its end and returns the lattice it
    /// froze into: `true` where the spin is up (lit).
    ///
    /// This is the snap. It is the same schedule
    /// ([`AnnealSchedule::default`]), the same sweep count
    /// ([`DEFAULT_TOTAL_SWEEPS`]) and the same dynamics the landing page
    /// scrolls through, stopped at the end of the schedule — so a brand
    /// image is the last frame of the page's own animation rather than a
    /// drawing of one.
    pub fn crystallise(&self) -> Lattice {
        let (width, height) = self.lattice;
        let spins = run_full_anneal_pinned(
            width,
            height,
            self.seed,
            DEFAULT_TOTAL_SWEEPS,
            &AnnealSchedule::default(),
            &self.mask(),
            &self.speck_sites(),
        );
        Lattice {
            width,
            height,
            lit: spins.iter().map(|&spin| spin > 0).collect(),
        }
    }

    /// The fraction of sites that came out agreeing with the mask —  the
    /// same measure `anneal.rs`'s crystallisation property test applies to
    /// the landing page, applied here to a mark that is not the wordmark
    /// and a lattice that is not 220x160.
    pub fn agreement(&self) -> f32 {
        let mask = self.mask();
        let lattice = self.crystallise();
        let agree = lattice
            .lit
            .iter()
            .zip(&mask)
            .filter(|(lit, wanted)| lit == wanted)
            .count();
        agree as f32 / mask.len() as f32
    }
}

/// Lights every site of `mask` within `radius` of `centre`.
fn paint_disc(mask: &mut [bool], size: (usize, usize), centre: (f32, f32), radius: f32) {
    let (width, height) = size;
    for y in 0..height {
        for x in 0..width {
            let (dx, dy) = (x as f32 + 0.5 - centre.0, y as f32 + 0.5 - centre.1);
            if (dx * dx + dy * dy).sqrt() <= radius {
                mask[y * width + x] = true;
            }
        }
    }
}

/// A finished lattice: one bit a site, row major.
pub struct Lattice {
    /// Sites across.
    pub width: usize,
    /// Sites down.
    pub height: usize,
    /// `true` where the spin is up — the lit colour.
    pub lit: Vec<bool>,
}

impl Lattice {
    /// Whether the site at `(x, y)` is lit; `false` outside the lattice.
    pub fn lit_at(&self, x: usize, y: usize) -> bool {
        x < self.width && y < self.height && self.lit[y * self.width + x]
    }

    /// The bounding box of the lit sites inside `mask`'s shape, grown by
    /// `margin` sites and clamped to the lattice: `(x, y, width, height)`.
    /// What a cropped logo is cropped to.
    pub fn mask_bounds(mask: &[bool], width: usize, height: usize, margin: usize) -> Rect {
        let (mut min_x, mut min_y, mut max_x, mut max_y) = (width, height, 0usize, 0usize);
        for y in 0..height {
            for x in 0..width {
                if mask[y * width + x] {
                    min_x = min_x.min(x);
                    min_y = min_y.min(y);
                    max_x = max_x.max(x);
                    max_y = max_y.max(y);
                }
            }
        }
        if min_x > max_x {
            return Rect {
                x: 0,
                y: 0,
                width,
                height,
            };
        }
        let x = min_x.saturating_sub(margin);
        let y = min_y.saturating_sub(margin);
        Rect {
            x,
            y,
            width: (max_x + margin + 1).min(width) - x,
            height: (max_y + margin + 1).min(height) - y,
        }
    }
}

/// A rectangle of lattice sites.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Rect {
    /// Leftmost site, in lattice coordinates.
    pub x: usize,
    /// Topmost site, in lattice coordinates.
    pub y: usize,
    /// Sites across.
    pub width: usize,
    /// Sites down.
    pub height: usize,
}

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

    /// Every mark has to actually come out looking like itself. The floor
    /// is the landing page's own (`anneal.rs`'s `AGREEMENT_FLOOR`, 93%),
    /// applied to lattices and shapes that test never saw: a schedule
    /// tuned for one 220x160 wordmark is not owed good behaviour on a
    /// 16x16 tile, so this is the test that says whether a mark is
    /// shippable at all.
    #[test]
    fn every_mark_crystallises_into_its_own_shape() {
        let mut failures = Vec::new();
        for mark in ALL {
            let agreement = mark.agreement();
            if agreement < 0.93 {
                failures.push((mark.name, agreement));
            }
        }
        assert!(
            failures.is_empty(),
            "marks that did not crystallise: {failures:?}"
        );
    }

    /// The specks' whole reason for being pinned. A lit site this small
    /// is not something the field can hold — the island around it is a
    /// site or two across at the tile sizes that carry specks — so
    /// without the pin the anneal erases them, and the signature is
    /// present in the mask and absent from the picture.
    #[test]
    fn every_speck_survives_the_anneal() {
        for mark in ALL.iter().filter(|mark| mark.specks != Specks::None) {
            let lattice = mark.crystallise();
            for (x, y) in mark.speck_sites() {
                assert!(
                    lattice.lit_at(x, y),
                    "{}: the speck at ({x}, {y}) did not survive",
                    mark.name
                );
            }
        }
    }

    /// A speck has to be inside the tile it decorates, and the three of
    /// them have to be three: a position that rounds onto another one, or
    /// off the lattice, is a silently missing part of the mark.
    #[test]
    fn the_specks_are_three_distinct_sites_inside_the_tile() {
        for mark in ALL.iter().filter(|mark| mark.specks != Specks::None) {
            let mut sites = mark.speck_sites();
            assert_eq!(sites.len(), 3, "{}", mark.name);
            for &(x, y) in &sites {
                assert!(x < mark.lattice.0 && y < mark.lattice.1, "{}", mark.name);
            }
            sites.sort_unstable();
            sites.dedup();
            assert_eq!(
                sites.len(),
                3,
                "{}: two specks landed on one site",
                mark.name
            );
        }
    }

    /// The property the whole crate rests on: a mark is a pure function,
    /// which is what lets the images be committed and checked. Run on the
    /// smallest lattice, because the property is the anneal's and not this
    /// mark's — the expensive ones are annealed once each above.
    #[test]
    fn the_same_mark_crystallises_into_the_same_lattice_every_time() {
        let once = DOT.crystallise();
        let again = DOT.crystallise();
        assert_eq!(once.lit, again.lit);
    }
}