Struct LegendKeySpec 

pub struct LegendKeySpec {
    pub kind: LegendKey,
    pub bindings: HashMap<String, AestheticSource>,
}

One key in a legend’s stack — what to draw + how to resolve its aesthetics for the current row.

Fields

kind: LegendKey

bindings: HashMap<String, AestheticSource>

Per-aesthetic name → source. Aesthetics not listed fall back to the key’s built-in default.

Implementations

impl LegendKeySpec

pub fn point() -> Self

Start a Point key with no aesthetic bindings.

Examples found in repository

examples/rich_text_chrome.rs (line 82)

fn main() {
    let (w, h) = (900u32, 560u32);
    let dpi = 96.0;
    let bg: Color = rgb8(250, 250, 253);

    let comp = || Composition::empty(1, 1).place(1, 1, Span::cell(), Patch::new("p"));

    let n = 60;
    let xs: Vec<f64> = (0..n).map(|i| i as f64 / (n - 1) as f64 * 10.0).collect();
    let ys: Vec<f64> = xs
        .iter()
        .map(|x| 2.5 + 1.2 * (x * 0.7).sin() + 0.4 * (x * 2.1).cos())
        .collect();

    // Break labels are data-derived, so a category that spells
    // markdown gets parsed like any other string.
    let bands: [&'static str; 3] = ["*low*", "**mid**", "{.red high}"];
    let groups: Vec<&'static str> = ys
        .iter()
        .map(|y| match *y {
            v if v < 2.0 => bands[0],
            v if v < 3.0 => bands[1],
            _ => bands[2],
        })
        .collect();

    let mut plot = Plot::new(&comp(), "p")
        .bind("x", "x")
        .bind("y", "y")
        .bind("fill", "band")
        .title("Trend of **{#c14b4b price}** across the day")
        .subtitle("Metric: *closing_bid* — sampled hourly")
        .caption("n = **60**, source: {.gray internal}");
    plot.add_geom(
        PointGeom::builder()
            .set("x", xs)
            .set("y", ys)
            .set("fill", groups)
            .set("size", 8.0_f64)
            .build(),
    );
    plot.add_legend(
        Legend::new("band")
            .title("**band** of the *close*")
            .key(LegendKeySpec::point().scaled("fill", "band")),
    );
    plot.add_axis(
        Axis::rail("x", AxisPlacement::Cartesian(AxisSide::Bottom))
            .title("hour of day, {.gray *UTC*}"),
    );
    plot.add_axis(
        Axis::rail("y", AxisPlacement::Cartesian(AxisSide::Left)).title("**price** (USD)"),
    );

    let mut view = PlotComposition::new(&comp())
        .theme(markdown_chrome_theme())
        .add_scale("x", scale::continuous(0.0..=10.0))
        .add_scale("y", scale::continuous(0.0..=5.0))
        .add_scale(
            "band",
            scale::discrete(bands.iter().map(|b| Value::String(Arc::from(*b)))).range_colors([
                rgb8(88, 106, 195),
                rgb8(214, 146, 60),
                rgb8(193, 75, 75),
            ]),
        )
        .with_plot(plot);

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    {
        let scene = renderer.scene();
        scene.clear();
        view.render(scene, Size::new(w as f64, h as f64), dpi);
    }
    let mut pixels = vec![0u8; (w * h * 4) as usize];
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");
    let path = std::env::current_dir()
        .unwrap()
        .join("examples/rich_text_chrome.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());
}

examples/theme_legend_variants.rs (line 60)

fn main() {
    let (w, h) = (900u32, 600u32);
    let dpi = 96.0;

    let n = 24;
    let xs: Vec<f64> = (0..n).map(|i| i as f64 * 0.4).collect();
    let ys: Vec<f64> = (0..n)
        .map(|i| ((i as f64) * 0.5).sin() * 0.4 + 0.5)
        .collect();
    let cats: [&'static str; 4] = ["A", "B", "C", "D"];
    let fill_col: Vec<&'static str> = (0..n).map(|i| cats[i % 4]).collect();

    let mut plot = Plot::new(&comp(), "panel")
        .bind("x", "x")
        .bind("y", "y")
        .bind("fill", "category_color")
        .title("Two legends, one opts into the \"hero\" theme variant");
    plot.add_geom(
        PointGeom::builder()
            .set("x", xs)
            .set("y", ys)
            .set("fill", fill_col.clone())
            .set("size", 6.0_f64)
            .build(),
    );
    plot.add_axis(Axis::rail("x", AxisPlacement::Cartesian(AxisSide::Bottom)));
    plot.add_axis(Axis::rail("y", AxisPlacement::Cartesian(AxisSide::Left)));

    // First legend — opts into the "hero" variant.
    plot.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Right)
            .title("Category (hero)")
            .theme_variant("hero")
            .key(
                LegendKeySpec::point()
                    .scaled("fill", "category_color")
                    .fixed("stroke", Value::Color(rgb(0.0, 0.0, 0.0)))
                    .fixed("size", 6.0_f64),
            ),
    );
    // Second legend — uses the default LegendTheme.
    plot.add_legend(
        Legend::new("category_size")
            .side(LegendSide::Bottom)
            .title("Category (default)")
            .key(
                LegendKeySpec::point()
                    .scaled("fill", "category_color")
                    .fixed("size", 6.0_f64),
            ),
    );

    // Register a "hero" variant on the theme. Distinct background
    // tint + a denser margin to telegraph the emphasis.
    let hero = LegendTheme {
        background: Element::Set(RectElement {
            fill: Some(ThemeColor::mix(ThemeColor::Paper, ThemeColor::Accent, 0.18)),
            color: Some(ThemeColor::Accent),
            linewidth_pt: Some(Length::Abs(1.0)),
            ..RectElement::default()
        }),
        ..LegendTheme::default()
    };

    let theme = Theme::default().with_legend_variant("hero", hero);

    let mut view = PlotComposition::new(&comp())
        .add_scale("x", scale::continuous(0.0..=12.0))
        .add_scale("y", scale::continuous(0.0..=1.0))
        .add_scale(
            "category_color",
            scale::discrete(cats.iter().map(|s| Value::String((*s).into()))).range_colors([
                rgb8(220, 100, 80),
                rgb8(80, 160, 100),
                rgb8(80, 130, 200),
                rgb8(180, 100, 200),
            ]),
        )
        .add_scale(
            "category_size",
            scale::discrete(cats.iter().map(|s| Value::String((*s).into())))
                .range_numbers([4.0, 6.0, 8.0, 10.0]),
        )
        .theme(theme);
    view.attach_plot(plot);

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    let bg: Color = rgb8(252, 252, 252);
    {
        let scene = renderer.scene();
        scene.clear();
        view.render(scene, Size::new(w as f64, h as f64), dpi);
    }
    let mut pixels = vec![0u8; (w * h * 4) as usize];
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");
    let path = std::env::current_dir()
        .unwrap()
        .join("examples/theme_legend_variants.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());
}

examples/faceted.rs (line 106)

fn main() {
    let (w, h) = (1400u32, 700u32);
    let dpi = 96.0;

    let xs: Vec<f64> = (0..50).map(|i| i as f64 * 2.0).collect();
    let make = |phase: f64, amp: f64| -> Vec<f64> {
        xs.iter()
            .map(|x| 50.0 + amp * (x * 0.05 + phase).sin())
            .collect()
    };

    let datasets = [
        ("q1", make(0.0, 25.0), rgb8(220, 90, 70)),
        ("q2", make(1.5, 18.0), rgb8(70, 120, 220)),
        ("q3", make(3.0, 22.0), rgb8(70, 180, 120)),
        ("q4", make(4.5, 28.0), rgb8(180, 130, 80)),
        ("summary", make(0.0, 35.0), rgb8(130, 80, 180)),
    ];

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    let bg: Color = rgb8(248, 248, 252);

    // ── Renders 1 & 2: shared "time" scale across the unlocked layout
    {
        #[allow(unused_mut)]
        let mut view = PlotComposition::new(&comp_shape(None))
            .add_scale("time", scale::continuous(0.0..=100.0))
            .add_scale("y", scale::continuous(0.0..=100.0))
            .title("Sensor array")
            .subtitle("Four quadrants and a summary, sharing one time scale")
            .caption("Composition-level chrome spans every panel");
        attach_all(&mut view, &xs, &datasets);

        // One axis title and one legend for the whole grid, set on the
        // composition rather than on any single plot. The legend reads
        // its rows from the "series" scale's domain; no plot needs to
        // bind that scale for the legend to resolve it.
        let mut view = {
            let series: Vec<Value> = datasets.iter().map(|(id, _, _)| Value::from(*id)).collect();
            let colors: Vec<Color> = datasets.iter().map(|(_, _, c)| *c).collect();
            let mut view = view
                .add_scale("series", scale::discrete(series).range_colors(colors))
                .axis_title(AxisSide::Bottom, "Time (s)");
            view.add_legend(
                Legend::new("series")
                    .side(LegendSide::Right)
                    .title("Series")
                    .key(
                        LegendKeySpec::point()
                            .scaled("fill", "series")
                            .fixed("size", 6.0_f64),
                    ),
            );
            view
        };

        let issues = view.validate();
        if !issues.is_empty() {
            panic!("validate() reported issues: {issues:?}");
        }

        render_to(
            &mut renderer,
            &mut view,
            w,
            h,
            dpi,
            bg,
            "examples/faceted_1_initial.png",
        );

        view.update_scale("time", |s| s.set_domain_continuous(20.0, 60.0));
        render_to(
            &mut renderer,
            &mut view,
            w,
            h,
            dpi,
            bg,
            "examples/faceted_2_shared_zoom.png",
        );
    }

    // ── Render 3: aspect-locked. Outer `.aspect(1, 1)` propagates to
    //    every leaf panel; selective respect on the layout solver
    //    couples panel col/row at the locked ratio and lets unmarked
    //    fr tracks absorb slack. Wider viewport (1800×600) makes the
    //    lock visually obvious — without it, the 1×2 outer would give
    //    half the width to each side; with it, the leaf panels land
    //    at the locked ratio and the surrounding tracks soak up the
    //    horizontal slack.
    {
        let (lw, lh) = (1800u32, 600u32);
        let mut view = PlotComposition::new(&comp_shape(Some((1.0, 1.0))))
            .add_scale("time", scale::continuous(20.0..=60.0))
            .add_scale("y", scale::continuous(0.0..=100.0));
        attach_all(&mut view, &xs, &datasets);
        render_to(
            &mut renderer,
            &mut view,
            lw,
            lh,
            dpi,
            bg,
            "examples/faceted_3_aspect_locked.png",
        );
    }
}

examples/theme_text_align_to.rs (line 69)

fn main() {
    let (w, h) = (1400u32, 500u32);
    let dpi = 96.0;

    let comp = || beside(Patch::new("a"), Patch::new("b"));
    let xs: Vec<f64> = (0..40).map(|i| i as f64 * 0.15).collect();
    let ys: Vec<f64> = xs.iter().map(|x| (x * 0.7).sin() * 0.4 + 0.5).collect();
    let categories: Vec<&str> = xs
        .iter()
        .map(|x| match (*x as usize) % 4 {
            0 => "A",
            1 => "B",
            2 => "C",
            _ => "D",
        })
        .collect();

    let make_plot = |patch_id: &str, title: &str| {
        let mut plot = Plot::new(&comp(), patch_id)
            .bind("x", "x_scale")
            .bind("y", "y_scale")
            .bind("stroke", "category")
            .title(title);
        plot.add_geom(
            PointGeom::builder()
                .set("x", xs.clone())
                .set("y", ys.clone())
                .set("size", 6.0_f64)
                .set("fill", rgb(0.20, 0.45, 0.85))
                .set("stroke", categories.clone())
                .set("linewidth", 1.0_f64)
                .build(),
        );
        plot.add_axis(
            Axis::rail("x_scale", AxisPlacement::Cartesian(AxisSide::Bottom)).title("Time (s)"),
        );
        plot.add_axis(
            Axis::rail("y_scale", AxisPlacement::Cartesian(AxisSide::Left))
                .title("A wide y-axis title"),
        );
        plot.add_legend(
            Legend::new("category")
                .side(LegendSide::Right)
                .title("Group")
                .key(
                    hephaestus::plot::chrome::legend::LegendKeySpec::point()
                        .scaled("stroke", "category"),
                ),
        );
        plot
    };

    let category_scale = scale::discrete([
        hephaestus::scales::Value::String(std::sync::Arc::from("A")),
        hephaestus::scales::Value::String(std::sync::Arc::from("B")),
        hephaestus::scales::Value::String(std::sync::Arc::from("C")),
        hephaestus::scales::Value::String(std::sync::Arc::from("D")),
    ])
    .range_colors([
        hephaestus::color::rgb(0.20, 0.20, 0.20),
        hephaestus::color::rgb(0.70, 0.20, 0.20),
        hephaestus::color::rgb(0.20, 0.60, 0.20),
        hephaestus::color::rgb(0.20, 0.20, 0.70),
    ]);

    // Left-align the title so its left edge anchors visibly differ
    // between the two `AlignTo` modes — under `Plot` it lands at
    // the left edge of the legend / plot interior; under `Panel`
    // it lands at the left edge of the panel itself. Mutating
    // `plot_title` in place (rather than constructing a new
    // `Element::Set(...)`) preserves the existing 16pt-bold styling
    // from `Theme::default`.
    let mut theme = Theme {
        plot_text_align_to: AlignTo::Plot,
        ..Theme::default()
    };
    if let Element::Set(t) = &mut theme.plot_title {
        t.align = Some(HAlign::Start);
    }
    let mut view = PlotComposition::new(&comp())
        .add_scale("x_scale", scale::continuous(0.0..=6.0))
        .add_scale("y_scale", scale::continuous(0.0..=1.0))
        .add_scale("category", category_scale)
        .theme(theme);
    view.attach_plot(make_plot(
        "a",
        "AlignTo::Plot — title left-edge aligns to plot interior",
    ));
    // Second plot uses a per-plot theme override to flip to Panel.
    view.attach_plot(
        make_plot("b", "AlignTo::Panel — title left-edge aligns to panel").theme_override(
            hephaestus::plot::theme::ThemePart {
                plot_text_align_to: Some(AlignTo::Panel),
                ..hephaestus::plot::theme::ThemePart::default()
            },
        ),
    );

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    let bg: Color = rgb8(245, 245, 245);
    {
        let scene = renderer.scene();
        scene.clear();
        view.render(scene, Size::new(w as f64, h as f64), dpi);
    }
    let mut pixels = vec![0u8; (w * h * 4) as usize];
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");
    let path = std::env::current_dir()
        .unwrap()
        .join("examples/theme_text_align_to.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());
}

examples/theme_plot_background.rs (line 91)

fn main() {
    let (w, h) = (900u32, 600u32);
    let dpi = 96.0;

    let comp = || Composition::empty(1, 1).place(1, 1, Span::cell(), Patch::new("p"));
    // Generate data that explicitly reaches the corners so the
    // rounded clip is visibly exercised. The dense corner clusters
    // get cropped by the rounded panel boundary.
    let mut xs: Vec<f64> = Vec::new();
    let mut ys: Vec<f64> = Vec::new();
    for i in 0..40 {
        let t = i as f64 / 39.0;
        xs.push(t * 6.0);
        ys.push((t * 4.4).sin() * 0.4 + 0.5);
    }
    // Add a corner-hugging cluster at all four corners to make clip
    // behaviour visible.
    for (cx, cy) in &[(0.05, 0.97), (5.95, 0.97), (0.05, 0.03), (5.95, 0.03)] {
        for di in 0..8 {
            let theta = di as f64 * 0.3;
            xs.push(cx + theta.cos() * 0.15);
            ys.push(cy + theta.sin() * 0.04);
        }
    }

    // Use the y values themselves as the colour-mapped channel so a
    // colorbar legend makes sense.
    let colours: Vec<f64> = ys.clone();
    // A second, discrete category column (assigned by x bucket),
    // used to drive the categorical stroke colour and a discrete
    // legend on the right next to the colorbar.
    let categories: Vec<&str> = xs
        .iter()
        .map(|x| match (*x as usize) % 4 {
            0 => "A",
            1 => "B",
            2 => "C",
            _ => "D",
        })
        .collect();
    let mut plot = Plot::new(&comp(), "p")
        .bind("x", "x_scale")
        .bind("y", "y_scale")
        .bind("fill", "fill_scale")
        .bind("stroke", "stroke_scale")
        .title("Rounded corners — plot bg, panel bg, frames");
    plot.add_geom(
        PointGeom::builder()
            .set("x", xs)
            .set("y", ys)
            .set("size", 8.0_f64)
            .set("fill", colours)
            .set("stroke", categories)
            .set("linewidth", 1.0_f64)
            .build(),
    );
    plot.add_axis(Axis::rail(
        "x_scale",
        AxisPlacement::Cartesian(AxisSide::Bottom),
    ));
    plot.add_axis(Axis::rail(
        "y_scale",
        AxisPlacement::Cartesian(AxisSide::Left),
    ));
    plot.add_legend(
        Legend::colorbar("fill_scale")
            .side(LegendSide::Right)
            .title("Amplitude"),
    );
    plot.add_legend(
        Legend::new("stroke_scale")
            .side(LegendSide::Right)
            .title("Group")
            .key(LegendKeySpec::point().scaled("stroke", "stroke_scale")),
    );

    // Two outer bands: 24pt `plot_margin` sits outside the
    // background; 18pt `plot_padding` sits inside it. Both feed the
    // anatomical ring tracks, so chrome lands in the correct rhythm
    // automatically.
    let theme = Theme {
        plot_margin: Margin::all(Length::Abs(24.0)),
        plot_padding: Margin::all(Length::Abs(18.0)),
        plot_background: Element::Set(RectElement {
            fill: Some(ThemeColor::mix(ThemeColor::Paper, ThemeColor::Accent, 0.3)),
            color: Some(ThemeColor::Ink),
            linewidth_pt: Some(Length::Abs(2.0)),
            corner_radius: Some(Length::Abs(12.0)),
            ..RectElement::default()
        }),
        // Round the panel corners too — the geom clip mask uses the
        // same rounded path so data points crop cleanly.
        panel_background: Element::Set(RectElement {
            corner_radius: Some(Length::Abs(8.0)),
            ..Theme::default().panel_background.as_set().unwrap().clone()
        }),
        // Colorbar bar + discrete key frames share `RectElement`
        // semantics: fill paints under the inner content (gradient
        // for the colorbar, marker for the key) so transparent
        // colours show the frame fill; stroke + corner_radius paint
        // on top.
        legend: hephaestus::plot::theme::LegendTheme {
            bar: hephaestus::plot::theme::BarTheme {
                frame: Element::Set(RectElement {
                    fill: Some(ThemeColor::mix(ThemeColor::Paper, ThemeColor::Ink, 0.08)),
                    color: Some(ThemeColor::Ink),
                    linewidth_pt: Some(Length::Abs(1.5)),
                    corner_radius: Some(Length::Abs(6.0)),
                    ..RectElement::default()
                }),
                ..hephaestus::plot::theme::BarTheme::default()
            },
            key: hephaestus::plot::theme::KeyTheme {
                width: Length::Abs(20.0),
                height: Length::Abs(20.0),
                frame: Element::Set(RectElement {
                    fill: Some(ThemeColor::mix(ThemeColor::Paper, ThemeColor::Ink, 0.08)),
                    color: Some(ThemeColor::Ink),
                    linewidth_pt: Some(Length::Abs(0.75)),
                    corner_radius: Some(Length::Abs(4.0)),
                    ..RectElement::default()
                }),
                ..hephaestus::plot::theme::KeyTheme::default()
            },
            ..Theme::default().legend
        },
        ..Theme::default()
    };

    let fill_scale = scale::continuous(0.0..=1.0).range_colors([
        hephaestus::color::rgb(0.2, 0.3, 0.6),
        hephaestus::color::rgb(0.85, 0.45, 0.2),
    ]);
    let stroke_scale = scale::discrete([
        hephaestus::scales::Value::String(std::sync::Arc::from("A")),
        hephaestus::scales::Value::String(std::sync::Arc::from("B")),
        hephaestus::scales::Value::String(std::sync::Arc::from("C")),
        hephaestus::scales::Value::String(std::sync::Arc::from("D")),
    ])
    .range_colors([
        hephaestus::color::rgb(0.20, 0.20, 0.20),
        hephaestus::color::rgb(0.70, 0.20, 0.20),
        hephaestus::color::rgb(0.20, 0.60, 0.20),
        hephaestus::color::rgb(0.20, 0.20, 0.70),
    ]);
    let mut view = PlotComposition::new(&comp())
        .add_scale("x_scale", scale::continuous(0.0..=6.0))
        .add_scale("y_scale", scale::continuous(0.0..=1.0))
        .add_scale("fill_scale", fill_scale)
        .add_scale("stroke_scale", stroke_scale)
        .theme(theme);
    view.attach_plot(plot);

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    // Contrasting canvas bg makes the plot_margin band visible
    // outside the (warm-cream) plot_background.
    let bg: Color = rgb8(60, 70, 90);
    {
        let scene = renderer.scene();
        scene.clear();
        view.render(scene, Size::new(w as f64, h as f64), dpi);
    }
    let mut pixels = vec![0u8; (w * h * 4) as usize];
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");
    let path = std::env::current_dir()
        .unwrap()
        .join("examples/theme_plot_background.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());
}

examples/legends.rs (line 106)

fn main() {
    let (w, h) = (900u32, 600u32);
    let dpi = 96.0;

    // ── Data ──
    let n = 24;
    let xs: Vec<f64> = (0..n).map(|i| i as f64 * 0.4).collect();
    let ys: Vec<f64> = (0..n)
        .map(|i| ((i as f64) * 0.5).sin() * 0.4 + 0.5)
        .collect();
    let cats: [&'static str; 4] = ["A", "B", "C", "D"];
    let fill_col: Vec<&'static str> = (0..n).map(|i| cats[i % 4]).collect();
    let size_col: Vec<&'static str> = (0..n).map(|i| cats[i % 4]).collect();

    // Build the plot's shape registry with the built-in vector
    // shapes plus a handful of emoji glyphs used by the binned
    // legend below. Glyph shapes share the same registry surface
    // as the vector ones (insert by name; look up by name) so the
    // legend chrome can resolve either.
    let glyph_style = TextStyle::new(16.0);
    let mut shapes = ShapeRegistry::with_builtins();
    // U+1F4A7 droplet, U+1F31E sun, U+1F525 fire, U+1F33F herb,
    // U+1F30A wave — picked to read as a "low → high" intensity
    // ramp matching the gradient_scale values.
    shapes.insert("droplet", glyph_marker("\u{1F4A7}", &glyph_style));
    shapes.insert("herb", glyph_marker("\u{1F33F}", &glyph_style));
    shapes.insert("sun", glyph_marker("\u{1F31E}", &glyph_style));
    shapes.insert("wave", glyph_marker("\u{1F30A}", &glyph_style));
    shapes.insert("fire", glyph_marker("\u{1F525}", &glyph_style));

    let mut p = Plot::new(&comp(), "panel")
        .bind("x", "x")
        .bind("y", "y")
        .bind("fill", "category_color")
        .bind("size", "category_size")
        .shape_registry(shapes);
    p.add_geom(
        PointGeom::builder()
            .set("x", xs)
            .set("y", ys)
            .set("fill", fill_col)
            .set("size", size_col)
            .build(),
    );
    p.add_axis(Axis::rail("x", AxisPlacement::Cartesian(AxisSide::Bottom)));
    p.add_axis(Axis::rail("y", AxisPlacement::Cartesian(AxisSide::Left)));

    // ── Right side, legend #1: line + point, both driven by
    // category_color. Attached as two legends; they share a side,
    // title and domain scale, so the render-time collapse folds the
    // second one's key into the first.
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Right)
            .title("Category")
            .key(LegendKeySpec::line().scaled("stroke", "category_color")),
    );
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Right)
            .title("Category")
            .key(
                LegendKeySpec::point()
                    .scaled("fill", "category_color")
                    .fixed("stroke", Value::Color(rgb(0.0, 0.0, 0.0)))
                    .fixed("size", 6.0_f64),
            ),
    );

    // ── Right side, legend #2 (stacks below #1): a size legend that
    // shares the Right slot. `category_size` is trained to the same
    // categories as `category_color`, so what keeps this a block of
    // its own is the differing title; the per-side stacker then
    // arranges both legends vertically.
    p.add_legend(
        Legend::new("category_size")
            .side(LegendSide::Right)
            .title("Size")
            .key(
                LegendKeySpec::point()
                    .scaled("size", "category_size")
                    .fixed("fill", Value::Color(rgb(0.25, 0.25, 0.25))),
            ),
    );

    // ── Right side, legend #3: a continuous gradient colorbar
    // driven by `gradient_scale`. Stacks below the discrete ones
    // via the same per-side stacker. The colorbar also pulls its
    // opacity from `gradient_opacity` — same domain → low values are
    // mostly transparent, high values fully opaque.
    p.add_legend(
        Legend::colorbar("gradient_scale")
            .side(LegendSide::Right)
            .title("Gradient")
            .scaled("fill_opacity", "gradient_opacity"),
    );

    // ── Bottom side, legend #3: same gradient scale but rendered
    // as discrete steps at each break — useful for showing a
    // binned colour mapping or any colorbar you want to read as
    // categorical bands. Routed to the Bottom slot so it stacks
    // horizontally alongside the existing "Pattern" + "Colour"
    // legends.
    p.add_legend(
        Legend::colorbar("gradient_scale")
            .side(LegendSide::Bottom)
            .title("Steps")
            .binned()
            .open_upper(),
    );

    // ── Bottom side, legend #4: a **binned stack** that varies
    // SHAPE per bin (instead of colour like the stepped colorbar
    // next to it). Six bin boundaries from `gradient_scale` → five
    // bins, each rendered as a different emoji-glyph shape via the
    // `bin_shape` scale (resolved against the plot's shape
    // registry). Demonstrates that the same legend key wiring
    // works with vector and glyph-backed shapes.
    //
    // Emoji glyphs fill their em-bbox almost completely (Latin
    // letters and vector circles only fill ~70–80 % of the same
    // bbox), so a 12pt emoji reads at roughly the same visual
    // weight as the 16pt circle markers used by the other legends.
    p.add_legend(
        Legend::new("gradient_scale")
            .side(LegendSide::Bottom)
            .title("Bins")
            .binned()
            .equal_bins()
            .key(
                LegendKeySpec::point()
                    .scaled("shape", "bin_shape")
                    .fixed("fill", Value::Color(rgb(0.15, 0.15, 0.15)))
                    .fixed("size", 12.0_f64),
            ),
    );

    // ── Left side: a text key. The swatch is a glyph sample rather
    // than a marker, so a font-size scale shows what it actually
    // does to type. `size` is the font size in pt and `fill` is the
    // ink; both resolve per row through their own scale.
    p.add_legend(
        Legend::new("category_size")
            .side(LegendSide::Left)
            .title("Font size")
            .key(
                LegendKeySpec::text()
                    .scaled("size", "category_size")
                    .scaled("fill", "category_color")
                    .fixed("text", Value::String(Arc::from("Aa"))),
            ),
    );

    // ── Bottom side: two legends side-by-side (horizontal stack).
    p.add_legend(
        Legend::new("category_line")
            .side(LegendSide::Bottom)
            .title("Pattern")
            .key(
                LegendKeySpec::line()
                    .scaled("linetype", "category_line")
                    .fixed("linewidth", 1.5_f64),
            ),
    );
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Bottom)
            .title("Colour")
            .key(LegendKeySpec::rect().scaled("fill", "category_color")),
    );

    // ── In-panel overlay: a compact category legend pinned to the
    // top-right corner of the panel area. Reserves no chrome space —
    // the data marks beneath continue to occupy the full panel rect.
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::InPanel {
                anchor: Anchor::TopRight,
                inset_pt: 8.0,
            })
            .title("Overlay")
            .key(
                LegendKeySpec::point()
                    .scaled("fill", "category_color")
                    .fixed("size", 6.0_f64),
            ),
    );

    let cat_values: Vec<Value> = cats.iter().map(|s| Value::String(Arc::from(*s))).collect();
    let line_cats: [&'static str; 3] = ["Solid", "Dashed", "Dotted"];
    let line_values: Vec<Value> = line_cats
        .iter()
        .map(|s| Value::String(Arc::from(*s)))
        .collect();

    let mut view = PlotComposition::new(&comp())
        .add_scale("x", scale::continuous(0.0..=10.0))
        .add_scale("y", scale::continuous(0.0..=1.0))
        .add_scale(
            "category_color",
            scale::discrete(cat_values.clone()).range_colors([
                rgb8(220, 90, 70),
                rgb8(70, 160, 90),
                rgb8(70, 120, 220),
                rgb8(180, 120, 200),
            ]),
        )
        .add_scale(
            "category_size",
            scale::discrete(cat_values).range_numbers([4.0, 8.0, 12.0, 16.0]),
        )
        .add_scale(
            "category_line",
            scale::discrete(line_values).range_linetypes([solid(), dashed(), dotted()]),
        )
        .add_scale(
            "gradient_scale",
            scale::continuous(0.0..=100.0).range_colors([
                rgb8(20, 30, 90),
                rgb8(60, 160, 200),
                rgb8(230, 220, 100),
                rgb8(220, 60, 40),
            ]),
        )
        .add_scale(
            "gradient_opacity",
            scale::continuous(0.0..=100.0).range_numbers([0.1, 1.0]),
        )
        .add_scale(
            "bin_shape",
            scale::continuous(0.0..=100.0).range_strings([
                Arc::from("droplet"),
                Arc::from("herb"),
                Arc::from("sun"),
                Arc::from("wave"),
                Arc::from("fire"),
            ]),
        );
    view.attach_plot(p);

    let issues = view.validate();
    if !issues.is_empty() {
        panic!("validate(): {issues:?}");
    }

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    let bg: Color = rgb8(252, 252, 252);
    {
        let scene = renderer.scene();
        scene.clear();
        view.render(scene, Size::new(w as f64, h as f64), dpi);
    }
    let mut pixels = vec![0u8; (w * h * 4) as usize];
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");
    let path = std::env::current_dir()
        .unwrap()
        .join("examples/legends.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());
}

pub fn line() -> Self

Start a Line key with no aesthetic bindings.

Examples found in repository

examples/legends.rs (line 99)

fn main() {
    let (w, h) = (900u32, 600u32);
    let dpi = 96.0;

    // ── Data ──
    let n = 24;
    let xs: Vec<f64> = (0..n).map(|i| i as f64 * 0.4).collect();
    let ys: Vec<f64> = (0..n)
        .map(|i| ((i as f64) * 0.5).sin() * 0.4 + 0.5)
        .collect();
    let cats: [&'static str; 4] = ["A", "B", "C", "D"];
    let fill_col: Vec<&'static str> = (0..n).map(|i| cats[i % 4]).collect();
    let size_col: Vec<&'static str> = (0..n).map(|i| cats[i % 4]).collect();

    // Build the plot's shape registry with the built-in vector
    // shapes plus a handful of emoji glyphs used by the binned
    // legend below. Glyph shapes share the same registry surface
    // as the vector ones (insert by name; look up by name) so the
    // legend chrome can resolve either.
    let glyph_style = TextStyle::new(16.0);
    let mut shapes = ShapeRegistry::with_builtins();
    // U+1F4A7 droplet, U+1F31E sun, U+1F525 fire, U+1F33F herb,
    // U+1F30A wave — picked to read as a "low → high" intensity
    // ramp matching the gradient_scale values.
    shapes.insert("droplet", glyph_marker("\u{1F4A7}", &glyph_style));
    shapes.insert("herb", glyph_marker("\u{1F33F}", &glyph_style));
    shapes.insert("sun", glyph_marker("\u{1F31E}", &glyph_style));
    shapes.insert("wave", glyph_marker("\u{1F30A}", &glyph_style));
    shapes.insert("fire", glyph_marker("\u{1F525}", &glyph_style));

    let mut p = Plot::new(&comp(), "panel")
        .bind("x", "x")
        .bind("y", "y")
        .bind("fill", "category_color")
        .bind("size", "category_size")
        .shape_registry(shapes);
    p.add_geom(
        PointGeom::builder()
            .set("x", xs)
            .set("y", ys)
            .set("fill", fill_col)
            .set("size", size_col)
            .build(),
    );
    p.add_axis(Axis::rail("x", AxisPlacement::Cartesian(AxisSide::Bottom)));
    p.add_axis(Axis::rail("y", AxisPlacement::Cartesian(AxisSide::Left)));

    // ── Right side, legend #1: line + point, both driven by
    // category_color. Attached as two legends; they share a side,
    // title and domain scale, so the render-time collapse folds the
    // second one's key into the first.
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Right)
            .title("Category")
            .key(LegendKeySpec::line().scaled("stroke", "category_color")),
    );
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Right)
            .title("Category")
            .key(
                LegendKeySpec::point()
                    .scaled("fill", "category_color")
                    .fixed("stroke", Value::Color(rgb(0.0, 0.0, 0.0)))
                    .fixed("size", 6.0_f64),
            ),
    );

    // ── Right side, legend #2 (stacks below #1): a size legend that
    // shares the Right slot. `category_size` is trained to the same
    // categories as `category_color`, so what keeps this a block of
    // its own is the differing title; the per-side stacker then
    // arranges both legends vertically.
    p.add_legend(
        Legend::new("category_size")
            .side(LegendSide::Right)
            .title("Size")
            .key(
                LegendKeySpec::point()
                    .scaled("size", "category_size")
                    .fixed("fill", Value::Color(rgb(0.25, 0.25, 0.25))),
            ),
    );

    // ── Right side, legend #3: a continuous gradient colorbar
    // driven by `gradient_scale`. Stacks below the discrete ones
    // via the same per-side stacker. The colorbar also pulls its
    // opacity from `gradient_opacity` — same domain → low values are
    // mostly transparent, high values fully opaque.
    p.add_legend(
        Legend::colorbar("gradient_scale")
            .side(LegendSide::Right)
            .title("Gradient")
            .scaled("fill_opacity", "gradient_opacity"),
    );

    // ── Bottom side, legend #3: same gradient scale but rendered
    // as discrete steps at each break — useful for showing a
    // binned colour mapping or any colorbar you want to read as
    // categorical bands. Routed to the Bottom slot so it stacks
    // horizontally alongside the existing "Pattern" + "Colour"
    // legends.
    p.add_legend(
        Legend::colorbar("gradient_scale")
            .side(LegendSide::Bottom)
            .title("Steps")
            .binned()
            .open_upper(),
    );

    // ── Bottom side, legend #4: a **binned stack** that varies
    // SHAPE per bin (instead of colour like the stepped colorbar
    // next to it). Six bin boundaries from `gradient_scale` → five
    // bins, each rendered as a different emoji-glyph shape via the
    // `bin_shape` scale (resolved against the plot's shape
    // registry). Demonstrates that the same legend key wiring
    // works with vector and glyph-backed shapes.
    //
    // Emoji glyphs fill their em-bbox almost completely (Latin
    // letters and vector circles only fill ~70–80 % of the same
    // bbox), so a 12pt emoji reads at roughly the same visual
    // weight as the 16pt circle markers used by the other legends.
    p.add_legend(
        Legend::new("gradient_scale")
            .side(LegendSide::Bottom)
            .title("Bins")
            .binned()
            .equal_bins()
            .key(
                LegendKeySpec::point()
                    .scaled("shape", "bin_shape")
                    .fixed("fill", Value::Color(rgb(0.15, 0.15, 0.15)))
                    .fixed("size", 12.0_f64),
            ),
    );

    // ── Left side: a text key. The swatch is a glyph sample rather
    // than a marker, so a font-size scale shows what it actually
    // does to type. `size` is the font size in pt and `fill` is the
    // ink; both resolve per row through their own scale.
    p.add_legend(
        Legend::new("category_size")
            .side(LegendSide::Left)
            .title("Font size")
            .key(
                LegendKeySpec::text()
                    .scaled("size", "category_size")
                    .scaled("fill", "category_color")
                    .fixed("text", Value::String(Arc::from("Aa"))),
            ),
    );

    // ── Bottom side: two legends side-by-side (horizontal stack).
    p.add_legend(
        Legend::new("category_line")
            .side(LegendSide::Bottom)
            .title("Pattern")
            .key(
                LegendKeySpec::line()
                    .scaled("linetype", "category_line")
                    .fixed("linewidth", 1.5_f64),
            ),
    );
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Bottom)
            .title("Colour")
            .key(LegendKeySpec::rect().scaled("fill", "category_color")),
    );

    // ── In-panel overlay: a compact category legend pinned to the
    // top-right corner of the panel area. Reserves no chrome space —
    // the data marks beneath continue to occupy the full panel rect.
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::InPanel {
                anchor: Anchor::TopRight,
                inset_pt: 8.0,
            })
            .title("Overlay")
            .key(
                LegendKeySpec::point()
                    .scaled("fill", "category_color")
                    .fixed("size", 6.0_f64),
            ),
    );

    let cat_values: Vec<Value> = cats.iter().map(|s| Value::String(Arc::from(*s))).collect();
    let line_cats: [&'static str; 3] = ["Solid", "Dashed", "Dotted"];
    let line_values: Vec<Value> = line_cats
        .iter()
        .map(|s| Value::String(Arc::from(*s)))
        .collect();

    let mut view = PlotComposition::new(&comp())
        .add_scale("x", scale::continuous(0.0..=10.0))
        .add_scale("y", scale::continuous(0.0..=1.0))
        .add_scale(
            "category_color",
            scale::discrete(cat_values.clone()).range_colors([
                rgb8(220, 90, 70),
                rgb8(70, 160, 90),
                rgb8(70, 120, 220),
                rgb8(180, 120, 200),
            ]),
        )
        .add_scale(
            "category_size",
            scale::discrete(cat_values).range_numbers([4.0, 8.0, 12.0, 16.0]),
        )
        .add_scale(
            "category_line",
            scale::discrete(line_values).range_linetypes([solid(), dashed(), dotted()]),
        )
        .add_scale(
            "gradient_scale",
            scale::continuous(0.0..=100.0).range_colors([
                rgb8(20, 30, 90),
                rgb8(60, 160, 200),
                rgb8(230, 220, 100),
                rgb8(220, 60, 40),
            ]),
        )
        .add_scale(
            "gradient_opacity",
            scale::continuous(0.0..=100.0).range_numbers([0.1, 1.0]),
        )
        .add_scale(
            "bin_shape",
            scale::continuous(0.0..=100.0).range_strings([
                Arc::from("droplet"),
                Arc::from("herb"),
                Arc::from("sun"),
                Arc::from("wave"),
                Arc::from("fire"),
            ]),
        );
    view.attach_plot(p);

    let issues = view.validate();
    if !issues.is_empty() {
        panic!("validate(): {issues:?}");
    }

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    let bg: Color = rgb8(252, 252, 252);
    {
        let scene = renderer.scene();
        scene.clear();
        view.render(scene, Size::new(w as f64, h as f64), dpi);
    }
    let mut pixels = vec![0u8; (w * h * 4) as usize];
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");
    let path = std::env::current_dir()
        .unwrap()
        .join("examples/legends.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());
}

pub fn rect() -> Self

Start a Rect key with no aesthetic bindings.

Examples found in repository

examples/legends.rs (line 212)

fn main() {
    let (w, h) = (900u32, 600u32);
    let dpi = 96.0;

    // ── Data ──
    let n = 24;
    let xs: Vec<f64> = (0..n).map(|i| i as f64 * 0.4).collect();
    let ys: Vec<f64> = (0..n)
        .map(|i| ((i as f64) * 0.5).sin() * 0.4 + 0.5)
        .collect();
    let cats: [&'static str; 4] = ["A", "B", "C", "D"];
    let fill_col: Vec<&'static str> = (0..n).map(|i| cats[i % 4]).collect();
    let size_col: Vec<&'static str> = (0..n).map(|i| cats[i % 4]).collect();

    // Build the plot's shape registry with the built-in vector
    // shapes plus a handful of emoji glyphs used by the binned
    // legend below. Glyph shapes share the same registry surface
    // as the vector ones (insert by name; look up by name) so the
    // legend chrome can resolve either.
    let glyph_style = TextStyle::new(16.0);
    let mut shapes = ShapeRegistry::with_builtins();
    // U+1F4A7 droplet, U+1F31E sun, U+1F525 fire, U+1F33F herb,
    // U+1F30A wave — picked to read as a "low → high" intensity
    // ramp matching the gradient_scale values.
    shapes.insert("droplet", glyph_marker("\u{1F4A7}", &glyph_style));
    shapes.insert("herb", glyph_marker("\u{1F33F}", &glyph_style));
    shapes.insert("sun", glyph_marker("\u{1F31E}", &glyph_style));
    shapes.insert("wave", glyph_marker("\u{1F30A}", &glyph_style));
    shapes.insert("fire", glyph_marker("\u{1F525}", &glyph_style));

    let mut p = Plot::new(&comp(), "panel")
        .bind("x", "x")
        .bind("y", "y")
        .bind("fill", "category_color")
        .bind("size", "category_size")
        .shape_registry(shapes);
    p.add_geom(
        PointGeom::builder()
            .set("x", xs)
            .set("y", ys)
            .set("fill", fill_col)
            .set("size", size_col)
            .build(),
    );
    p.add_axis(Axis::rail("x", AxisPlacement::Cartesian(AxisSide::Bottom)));
    p.add_axis(Axis::rail("y", AxisPlacement::Cartesian(AxisSide::Left)));

    // ── Right side, legend #1: line + point, both driven by
    // category_color. Attached as two legends; they share a side,
    // title and domain scale, so the render-time collapse folds the
    // second one's key into the first.
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Right)
            .title("Category")
            .key(LegendKeySpec::line().scaled("stroke", "category_color")),
    );
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Right)
            .title("Category")
            .key(
                LegendKeySpec::point()
                    .scaled("fill", "category_color")
                    .fixed("stroke", Value::Color(rgb(0.0, 0.0, 0.0)))
                    .fixed("size", 6.0_f64),
            ),
    );

    // ── Right side, legend #2 (stacks below #1): a size legend that
    // shares the Right slot. `category_size` is trained to the same
    // categories as `category_color`, so what keeps this a block of
    // its own is the differing title; the per-side stacker then
    // arranges both legends vertically.
    p.add_legend(
        Legend::new("category_size")
            .side(LegendSide::Right)
            .title("Size")
            .key(
                LegendKeySpec::point()
                    .scaled("size", "category_size")
                    .fixed("fill", Value::Color(rgb(0.25, 0.25, 0.25))),
            ),
    );

    // ── Right side, legend #3: a continuous gradient colorbar
    // driven by `gradient_scale`. Stacks below the discrete ones
    // via the same per-side stacker. The colorbar also pulls its
    // opacity from `gradient_opacity` — same domain → low values are
    // mostly transparent, high values fully opaque.
    p.add_legend(
        Legend::colorbar("gradient_scale")
            .side(LegendSide::Right)
            .title("Gradient")
            .scaled("fill_opacity", "gradient_opacity"),
    );

    // ── Bottom side, legend #3: same gradient scale but rendered
    // as discrete steps at each break — useful for showing a
    // binned colour mapping or any colorbar you want to read as
    // categorical bands. Routed to the Bottom slot so it stacks
    // horizontally alongside the existing "Pattern" + "Colour"
    // legends.
    p.add_legend(
        Legend::colorbar("gradient_scale")
            .side(LegendSide::Bottom)
            .title("Steps")
            .binned()
            .open_upper(),
    );

    // ── Bottom side, legend #4: a **binned stack** that varies
    // SHAPE per bin (instead of colour like the stepped colorbar
    // next to it). Six bin boundaries from `gradient_scale` → five
    // bins, each rendered as a different emoji-glyph shape via the
    // `bin_shape` scale (resolved against the plot's shape
    // registry). Demonstrates that the same legend key wiring
    // works with vector and glyph-backed shapes.
    //
    // Emoji glyphs fill their em-bbox almost completely (Latin
    // letters and vector circles only fill ~70–80 % of the same
    // bbox), so a 12pt emoji reads at roughly the same visual
    // weight as the 16pt circle markers used by the other legends.
    p.add_legend(
        Legend::new("gradient_scale")
            .side(LegendSide::Bottom)
            .title("Bins")
            .binned()
            .equal_bins()
            .key(
                LegendKeySpec::point()
                    .scaled("shape", "bin_shape")
                    .fixed("fill", Value::Color(rgb(0.15, 0.15, 0.15)))
                    .fixed("size", 12.0_f64),
            ),
    );

    // ── Left side: a text key. The swatch is a glyph sample rather
    // than a marker, so a font-size scale shows what it actually
    // does to type. `size` is the font size in pt and `fill` is the
    // ink; both resolve per row through their own scale.
    p.add_legend(
        Legend::new("category_size")
            .side(LegendSide::Left)
            .title("Font size")
            .key(
                LegendKeySpec::text()
                    .scaled("size", "category_size")
                    .scaled("fill", "category_color")
                    .fixed("text", Value::String(Arc::from("Aa"))),
            ),
    );

    // ── Bottom side: two legends side-by-side (horizontal stack).
    p.add_legend(
        Legend::new("category_line")
            .side(LegendSide::Bottom)
            .title("Pattern")
            .key(
                LegendKeySpec::line()
                    .scaled("linetype", "category_line")
                    .fixed("linewidth", 1.5_f64),
            ),
    );
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Bottom)
            .title("Colour")
            .key(LegendKeySpec::rect().scaled("fill", "category_color")),
    );

    // ── In-panel overlay: a compact category legend pinned to the
    // top-right corner of the panel area. Reserves no chrome space —
    // the data marks beneath continue to occupy the full panel rect.
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::InPanel {
                anchor: Anchor::TopRight,
                inset_pt: 8.0,
            })
            .title("Overlay")
            .key(
                LegendKeySpec::point()
                    .scaled("fill", "category_color")
                    .fixed("size", 6.0_f64),
            ),
    );

    let cat_values: Vec<Value> = cats.iter().map(|s| Value::String(Arc::from(*s))).collect();
    let line_cats: [&'static str; 3] = ["Solid", "Dashed", "Dotted"];
    let line_values: Vec<Value> = line_cats
        .iter()
        .map(|s| Value::String(Arc::from(*s)))
        .collect();

    let mut view = PlotComposition::new(&comp())
        .add_scale("x", scale::continuous(0.0..=10.0))
        .add_scale("y", scale::continuous(0.0..=1.0))
        .add_scale(
            "category_color",
            scale::discrete(cat_values.clone()).range_colors([
                rgb8(220, 90, 70),
                rgb8(70, 160, 90),
                rgb8(70, 120, 220),
                rgb8(180, 120, 200),
            ]),
        )
        .add_scale(
            "category_size",
            scale::discrete(cat_values).range_numbers([4.0, 8.0, 12.0, 16.0]),
        )
        .add_scale(
            "category_line",
            scale::discrete(line_values).range_linetypes([solid(), dashed(), dotted()]),
        )
        .add_scale(
            "gradient_scale",
            scale::continuous(0.0..=100.0).range_colors([
                rgb8(20, 30, 90),
                rgb8(60, 160, 200),
                rgb8(230, 220, 100),
                rgb8(220, 60, 40),
            ]),
        )
        .add_scale(
            "gradient_opacity",
            scale::continuous(0.0..=100.0).range_numbers([0.1, 1.0]),
        )
        .add_scale(
            "bin_shape",
            scale::continuous(0.0..=100.0).range_strings([
                Arc::from("droplet"),
                Arc::from("herb"),
                Arc::from("sun"),
                Arc::from("wave"),
                Arc::from("fire"),
            ]),
        );
    view.attach_plot(p);

    let issues = view.validate();
    if !issues.is_empty() {
        panic!("validate(): {issues:?}");
    }

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    let bg: Color = rgb8(252, 252, 252);
    {
        let scene = renderer.scene();
        scene.clear();
        view.render(scene, Size::new(w as f64, h as f64), dpi);
    }
    let mut pixels = vec![0u8; (w * h * 4) as usize];
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");
    let path = std::env::current_dir()
        .unwrap()
        .join("examples/legends.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());
}

pub fn text() -> Self

Start a Text key with no aesthetic bindings. The glyph is DEFAULT_KEY_TEXT until a "text" aesthetic names another one.

Examples found in repository

examples/legends.rs (line 190)

fn main() {
    let (w, h) = (900u32, 600u32);
    let dpi = 96.0;

    // ── Data ──
    let n = 24;
    let xs: Vec<f64> = (0..n).map(|i| i as f64 * 0.4).collect();
    let ys: Vec<f64> = (0..n)
        .map(|i| ((i as f64) * 0.5).sin() * 0.4 + 0.5)
        .collect();
    let cats: [&'static str; 4] = ["A", "B", "C", "D"];
    let fill_col: Vec<&'static str> = (0..n).map(|i| cats[i % 4]).collect();
    let size_col: Vec<&'static str> = (0..n).map(|i| cats[i % 4]).collect();

    // Build the plot's shape registry with the built-in vector
    // shapes plus a handful of emoji glyphs used by the binned
    // legend below. Glyph shapes share the same registry surface
    // as the vector ones (insert by name; look up by name) so the
    // legend chrome can resolve either.
    let glyph_style = TextStyle::new(16.0);
    let mut shapes = ShapeRegistry::with_builtins();
    // U+1F4A7 droplet, U+1F31E sun, U+1F525 fire, U+1F33F herb,
    // U+1F30A wave — picked to read as a "low → high" intensity
    // ramp matching the gradient_scale values.
    shapes.insert("droplet", glyph_marker("\u{1F4A7}", &glyph_style));
    shapes.insert("herb", glyph_marker("\u{1F33F}", &glyph_style));
    shapes.insert("sun", glyph_marker("\u{1F31E}", &glyph_style));
    shapes.insert("wave", glyph_marker("\u{1F30A}", &glyph_style));
    shapes.insert("fire", glyph_marker("\u{1F525}", &glyph_style));

    let mut p = Plot::new(&comp(), "panel")
        .bind("x", "x")
        .bind("y", "y")
        .bind("fill", "category_color")
        .bind("size", "category_size")
        .shape_registry(shapes);
    p.add_geom(
        PointGeom::builder()
            .set("x", xs)
            .set("y", ys)
            .set("fill", fill_col)
            .set("size", size_col)
            .build(),
    );
    p.add_axis(Axis::rail("x", AxisPlacement::Cartesian(AxisSide::Bottom)));
    p.add_axis(Axis::rail("y", AxisPlacement::Cartesian(AxisSide::Left)));

    // ── Right side, legend #1: line + point, both driven by
    // category_color. Attached as two legends; they share a side,
    // title and domain scale, so the render-time collapse folds the
    // second one's key into the first.
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Right)
            .title("Category")
            .key(LegendKeySpec::line().scaled("stroke", "category_color")),
    );
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Right)
            .title("Category")
            .key(
                LegendKeySpec::point()
                    .scaled("fill", "category_color")
                    .fixed("stroke", Value::Color(rgb(0.0, 0.0, 0.0)))
                    .fixed("size", 6.0_f64),
            ),
    );

    // ── Right side, legend #2 (stacks below #1): a size legend that
    // shares the Right slot. `category_size` is trained to the same
    // categories as `category_color`, so what keeps this a block of
    // its own is the differing title; the per-side stacker then
    // arranges both legends vertically.
    p.add_legend(
        Legend::new("category_size")
            .side(LegendSide::Right)
            .title("Size")
            .key(
                LegendKeySpec::point()
                    .scaled("size", "category_size")
                    .fixed("fill", Value::Color(rgb(0.25, 0.25, 0.25))),
            ),
    );

    // ── Right side, legend #3: a continuous gradient colorbar
    // driven by `gradient_scale`. Stacks below the discrete ones
    // via the same per-side stacker. The colorbar also pulls its
    // opacity from `gradient_opacity` — same domain → low values are
    // mostly transparent, high values fully opaque.
    p.add_legend(
        Legend::colorbar("gradient_scale")
            .side(LegendSide::Right)
            .title("Gradient")
            .scaled("fill_opacity", "gradient_opacity"),
    );

    // ── Bottom side, legend #3: same gradient scale but rendered
    // as discrete steps at each break — useful for showing a
    // binned colour mapping or any colorbar you want to read as
    // categorical bands. Routed to the Bottom slot so it stacks
    // horizontally alongside the existing "Pattern" + "Colour"
    // legends.
    p.add_legend(
        Legend::colorbar("gradient_scale")
            .side(LegendSide::Bottom)
            .title("Steps")
            .binned()
            .open_upper(),
    );

    // ── Bottom side, legend #4: a **binned stack** that varies
    // SHAPE per bin (instead of colour like the stepped colorbar
    // next to it). Six bin boundaries from `gradient_scale` → five
    // bins, each rendered as a different emoji-glyph shape via the
    // `bin_shape` scale (resolved against the plot's shape
    // registry). Demonstrates that the same legend key wiring
    // works with vector and glyph-backed shapes.
    //
    // Emoji glyphs fill their em-bbox almost completely (Latin
    // letters and vector circles only fill ~70–80 % of the same
    // bbox), so a 12pt emoji reads at roughly the same visual
    // weight as the 16pt circle markers used by the other legends.
    p.add_legend(
        Legend::new("gradient_scale")
            .side(LegendSide::Bottom)
            .title("Bins")
            .binned()
            .equal_bins()
            .key(
                LegendKeySpec::point()
                    .scaled("shape", "bin_shape")
                    .fixed("fill", Value::Color(rgb(0.15, 0.15, 0.15)))
                    .fixed("size", 12.0_f64),
            ),
    );

    // ── Left side: a text key. The swatch is a glyph sample rather
    // than a marker, so a font-size scale shows what it actually
    // does to type. `size` is the font size in pt and `fill` is the
    // ink; both resolve per row through their own scale.
    p.add_legend(
        Legend::new("category_size")
            .side(LegendSide::Left)
            .title("Font size")
            .key(
                LegendKeySpec::text()
                    .scaled("size", "category_size")
                    .scaled("fill", "category_color")
                    .fixed("text", Value::String(Arc::from("Aa"))),
            ),
    );

    // ── Bottom side: two legends side-by-side (horizontal stack).
    p.add_legend(
        Legend::new("category_line")
            .side(LegendSide::Bottom)
            .title("Pattern")
            .key(
                LegendKeySpec::line()
                    .scaled("linetype", "category_line")
                    .fixed("linewidth", 1.5_f64),
            ),
    );
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Bottom)
            .title("Colour")
            .key(LegendKeySpec::rect().scaled("fill", "category_color")),
    );

    // ── In-panel overlay: a compact category legend pinned to the
    // top-right corner of the panel area. Reserves no chrome space —
    // the data marks beneath continue to occupy the full panel rect.
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::InPanel {
                anchor: Anchor::TopRight,
                inset_pt: 8.0,
            })
            .title("Overlay")
            .key(
                LegendKeySpec::point()
                    .scaled("fill", "category_color")
                    .fixed("size", 6.0_f64),
            ),
    );

    let cat_values: Vec<Value> = cats.iter().map(|s| Value::String(Arc::from(*s))).collect();
    let line_cats: [&'static str; 3] = ["Solid", "Dashed", "Dotted"];
    let line_values: Vec<Value> = line_cats
        .iter()
        .map(|s| Value::String(Arc::from(*s)))
        .collect();

    let mut view = PlotComposition::new(&comp())
        .add_scale("x", scale::continuous(0.0..=10.0))
        .add_scale("y", scale::continuous(0.0..=1.0))
        .add_scale(
            "category_color",
            scale::discrete(cat_values.clone()).range_colors([
                rgb8(220, 90, 70),
                rgb8(70, 160, 90),
                rgb8(70, 120, 220),
                rgb8(180, 120, 200),
            ]),
        )
        .add_scale(
            "category_size",
            scale::discrete(cat_values).range_numbers([4.0, 8.0, 12.0, 16.0]),
        )
        .add_scale(
            "category_line",
            scale::discrete(line_values).range_linetypes([solid(), dashed(), dotted()]),
        )
        .add_scale(
            "gradient_scale",
            scale::continuous(0.0..=100.0).range_colors([
                rgb8(20, 30, 90),
                rgb8(60, 160, 200),
                rgb8(230, 220, 100),
                rgb8(220, 60, 40),
            ]),
        )
        .add_scale(
            "gradient_opacity",
            scale::continuous(0.0..=100.0).range_numbers([0.1, 1.0]),
        )
        .add_scale(
            "bin_shape",
            scale::continuous(0.0..=100.0).range_strings([
                Arc::from("droplet"),
                Arc::from("herb"),
                Arc::from("sun"),
                Arc::from("wave"),
                Arc::from("fire"),
            ]),
        );
    view.attach_plot(p);

    let issues = view.validate();
    if !issues.is_empty() {
        panic!("validate(): {issues:?}");
    }

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    let bg: Color = rgb8(252, 252, 252);
    {
        let scene = renderer.scene();
        scene.clear();
        view.render(scene, Size::new(w as f64, h as f64), dpi);
    }
    let mut pixels = vec![0u8; (w * h * 4) as usize];
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");
    let path = std::env::current_dir()
        .unwrap()
        .join("examples/legends.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());
}

pub fn scaled( self, aesthetic: impl Into<String>, scale_name: impl Into<String>, ) -> Self

Pull this aesthetic from scale_name at the row’s domain value.

Examples found in repository

examples/rich_text_chrome.rs (line 82)

fn main() {
    let (w, h) = (900u32, 560u32);
    let dpi = 96.0;
    let bg: Color = rgb8(250, 250, 253);

    let comp = || Composition::empty(1, 1).place(1, 1, Span::cell(), Patch::new("p"));

    let n = 60;
    let xs: Vec<f64> = (0..n).map(|i| i as f64 / (n - 1) as f64 * 10.0).collect();
    let ys: Vec<f64> = xs
        .iter()
        .map(|x| 2.5 + 1.2 * (x * 0.7).sin() + 0.4 * (x * 2.1).cos())
        .collect();

    // Break labels are data-derived, so a category that spells
    // markdown gets parsed like any other string.
    let bands: [&'static str; 3] = ["*low*", "**mid**", "{.red high}"];
    let groups: Vec<&'static str> = ys
        .iter()
        .map(|y| match *y {
            v if v < 2.0 => bands[0],
            v if v < 3.0 => bands[1],
            _ => bands[2],
        })
        .collect();

    let mut plot = Plot::new(&comp(), "p")
        .bind("x", "x")
        .bind("y", "y")
        .bind("fill", "band")
        .title("Trend of **{#c14b4b price}** across the day")
        .subtitle("Metric: *closing_bid* — sampled hourly")
        .caption("n = **60**, source: {.gray internal}");
    plot.add_geom(
        PointGeom::builder()
            .set("x", xs)
            .set("y", ys)
            .set("fill", groups)
            .set("size", 8.0_f64)
            .build(),
    );
    plot.add_legend(
        Legend::new("band")
            .title("**band** of the *close*")
            .key(LegendKeySpec::point().scaled("fill", "band")),
    );
    plot.add_axis(
        Axis::rail("x", AxisPlacement::Cartesian(AxisSide::Bottom))
            .title("hour of day, {.gray *UTC*}"),
    );
    plot.add_axis(
        Axis::rail("y", AxisPlacement::Cartesian(AxisSide::Left)).title("**price** (USD)"),
    );

    let mut view = PlotComposition::new(&comp())
        .theme(markdown_chrome_theme())
        .add_scale("x", scale::continuous(0.0..=10.0))
        .add_scale("y", scale::continuous(0.0..=5.0))
        .add_scale(
            "band",
            scale::discrete(bands.iter().map(|b| Value::String(Arc::from(*b)))).range_colors([
                rgb8(88, 106, 195),
                rgb8(214, 146, 60),
                rgb8(193, 75, 75),
            ]),
        )
        .with_plot(plot);

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    {
        let scene = renderer.scene();
        scene.clear();
        view.render(scene, Size::new(w as f64, h as f64), dpi);
    }
    let mut pixels = vec![0u8; (w * h * 4) as usize];
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");
    let path = std::env::current_dir()
        .unwrap()
        .join("examples/rich_text_chrome.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());
}

examples/theme_legend_variants.rs (line 61)

fn main() {
    let (w, h) = (900u32, 600u32);
    let dpi = 96.0;

    let n = 24;
    let xs: Vec<f64> = (0..n).map(|i| i as f64 * 0.4).collect();
    let ys: Vec<f64> = (0..n)
        .map(|i| ((i as f64) * 0.5).sin() * 0.4 + 0.5)
        .collect();
    let cats: [&'static str; 4] = ["A", "B", "C", "D"];
    let fill_col: Vec<&'static str> = (0..n).map(|i| cats[i % 4]).collect();

    let mut plot = Plot::new(&comp(), "panel")
        .bind("x", "x")
        .bind("y", "y")
        .bind("fill", "category_color")
        .title("Two legends, one opts into the \"hero\" theme variant");
    plot.add_geom(
        PointGeom::builder()
            .set("x", xs)
            .set("y", ys)
            .set("fill", fill_col.clone())
            .set("size", 6.0_f64)
            .build(),
    );
    plot.add_axis(Axis::rail("x", AxisPlacement::Cartesian(AxisSide::Bottom)));
    plot.add_axis(Axis::rail("y", AxisPlacement::Cartesian(AxisSide::Left)));

    // First legend — opts into the "hero" variant.
    plot.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Right)
            .title("Category (hero)")
            .theme_variant("hero")
            .key(
                LegendKeySpec::point()
                    .scaled("fill", "category_color")
                    .fixed("stroke", Value::Color(rgb(0.0, 0.0, 0.0)))
                    .fixed("size", 6.0_f64),
            ),
    );
    // Second legend — uses the default LegendTheme.
    plot.add_legend(
        Legend::new("category_size")
            .side(LegendSide::Bottom)
            .title("Category (default)")
            .key(
                LegendKeySpec::point()
                    .scaled("fill", "category_color")
                    .fixed("size", 6.0_f64),
            ),
    );

    // Register a "hero" variant on the theme. Distinct background
    // tint + a denser margin to telegraph the emphasis.
    let hero = LegendTheme {
        background: Element::Set(RectElement {
            fill: Some(ThemeColor::mix(ThemeColor::Paper, ThemeColor::Accent, 0.18)),
            color: Some(ThemeColor::Accent),
            linewidth_pt: Some(Length::Abs(1.0)),
            ..RectElement::default()
        }),
        ..LegendTheme::default()
    };

    let theme = Theme::default().with_legend_variant("hero", hero);

    let mut view = PlotComposition::new(&comp())
        .add_scale("x", scale::continuous(0.0..=12.0))
        .add_scale("y", scale::continuous(0.0..=1.0))
        .add_scale(
            "category_color",
            scale::discrete(cats.iter().map(|s| Value::String((*s).into()))).range_colors([
                rgb8(220, 100, 80),
                rgb8(80, 160, 100),
                rgb8(80, 130, 200),
                rgb8(180, 100, 200),
            ]),
        )
        .add_scale(
            "category_size",
            scale::discrete(cats.iter().map(|s| Value::String((*s).into())))
                .range_numbers([4.0, 6.0, 8.0, 10.0]),
        )
        .theme(theme);
    view.attach_plot(plot);

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    let bg: Color = rgb8(252, 252, 252);
    {
        let scene = renderer.scene();
        scene.clear();
        view.render(scene, Size::new(w as f64, h as f64), dpi);
    }
    let mut pixels = vec![0u8; (w * h * 4) as usize];
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");
    let path = std::env::current_dir()
        .unwrap()
        .join("examples/theme_legend_variants.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());
}

examples/faceted.rs (line 107)

fn main() {
    let (w, h) = (1400u32, 700u32);
    let dpi = 96.0;

    let xs: Vec<f64> = (0..50).map(|i| i as f64 * 2.0).collect();
    let make = |phase: f64, amp: f64| -> Vec<f64> {
        xs.iter()
            .map(|x| 50.0 + amp * (x * 0.05 + phase).sin())
            .collect()
    };

    let datasets = [
        ("q1", make(0.0, 25.0), rgb8(220, 90, 70)),
        ("q2", make(1.5, 18.0), rgb8(70, 120, 220)),
        ("q3", make(3.0, 22.0), rgb8(70, 180, 120)),
        ("q4", make(4.5, 28.0), rgb8(180, 130, 80)),
        ("summary", make(0.0, 35.0), rgb8(130, 80, 180)),
    ];

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    let bg: Color = rgb8(248, 248, 252);

    // ── Renders 1 & 2: shared "time" scale across the unlocked layout
    {
        #[allow(unused_mut)]
        let mut view = PlotComposition::new(&comp_shape(None))
            .add_scale("time", scale::continuous(0.0..=100.0))
            .add_scale("y", scale::continuous(0.0..=100.0))
            .title("Sensor array")
            .subtitle("Four quadrants and a summary, sharing one time scale")
            .caption("Composition-level chrome spans every panel");
        attach_all(&mut view, &xs, &datasets);

        // One axis title and one legend for the whole grid, set on the
        // composition rather than on any single plot. The legend reads
        // its rows from the "series" scale's domain; no plot needs to
        // bind that scale for the legend to resolve it.
        let mut view = {
            let series: Vec<Value> = datasets.iter().map(|(id, _, _)| Value::from(*id)).collect();
            let colors: Vec<Color> = datasets.iter().map(|(_, _, c)| *c).collect();
            let mut view = view
                .add_scale("series", scale::discrete(series).range_colors(colors))
                .axis_title(AxisSide::Bottom, "Time (s)");
            view.add_legend(
                Legend::new("series")
                    .side(LegendSide::Right)
                    .title("Series")
                    .key(
                        LegendKeySpec::point()
                            .scaled("fill", "series")
                            .fixed("size", 6.0_f64),
                    ),
            );
            view
        };

        let issues = view.validate();
        if !issues.is_empty() {
            panic!("validate() reported issues: {issues:?}");
        }

        render_to(
            &mut renderer,
            &mut view,
            w,
            h,
            dpi,
            bg,
            "examples/faceted_1_initial.png",
        );

        view.update_scale("time", |s| s.set_domain_continuous(20.0, 60.0));
        render_to(
            &mut renderer,
            &mut view,
            w,
            h,
            dpi,
            bg,
            "examples/faceted_2_shared_zoom.png",
        );
    }

    // ── Render 3: aspect-locked. Outer `.aspect(1, 1)` propagates to
    //    every leaf panel; selective respect on the layout solver
    //    couples panel col/row at the locked ratio and lets unmarked
    //    fr tracks absorb slack. Wider viewport (1800×600) makes the
    //    lock visually obvious — without it, the 1×2 outer would give
    //    half the width to each side; with it, the leaf panels land
    //    at the locked ratio and the surrounding tracks soak up the
    //    horizontal slack.
    {
        let (lw, lh) = (1800u32, 600u32);
        let mut view = PlotComposition::new(&comp_shape(Some((1.0, 1.0))))
            .add_scale("time", scale::continuous(20.0..=60.0))
            .add_scale("y", scale::continuous(0.0..=100.0));
        attach_all(&mut view, &xs, &datasets);
        render_to(
            &mut renderer,
            &mut view,
            lw,
            lh,
            dpi,
            bg,
            "examples/faceted_3_aspect_locked.png",
        );
    }
}

examples/theme_text_align_to.rs (line 70)

fn main() {
    let (w, h) = (1400u32, 500u32);
    let dpi = 96.0;

    let comp = || beside(Patch::new("a"), Patch::new("b"));
    let xs: Vec<f64> = (0..40).map(|i| i as f64 * 0.15).collect();
    let ys: Vec<f64> = xs.iter().map(|x| (x * 0.7).sin() * 0.4 + 0.5).collect();
    let categories: Vec<&str> = xs
        .iter()
        .map(|x| match (*x as usize) % 4 {
            0 => "A",
            1 => "B",
            2 => "C",
            _ => "D",
        })
        .collect();

    let make_plot = |patch_id: &str, title: &str| {
        let mut plot = Plot::new(&comp(), patch_id)
            .bind("x", "x_scale")
            .bind("y", "y_scale")
            .bind("stroke", "category")
            .title(title);
        plot.add_geom(
            PointGeom::builder()
                .set("x", xs.clone())
                .set("y", ys.clone())
                .set("size", 6.0_f64)
                .set("fill", rgb(0.20, 0.45, 0.85))
                .set("stroke", categories.clone())
                .set("linewidth", 1.0_f64)
                .build(),
        );
        plot.add_axis(
            Axis::rail("x_scale", AxisPlacement::Cartesian(AxisSide::Bottom)).title("Time (s)"),
        );
        plot.add_axis(
            Axis::rail("y_scale", AxisPlacement::Cartesian(AxisSide::Left))
                .title("A wide y-axis title"),
        );
        plot.add_legend(
            Legend::new("category")
                .side(LegendSide::Right)
                .title("Group")
                .key(
                    hephaestus::plot::chrome::legend::LegendKeySpec::point()
                        .scaled("stroke", "category"),
                ),
        );
        plot
    };

    let category_scale = scale::discrete([
        hephaestus::scales::Value::String(std::sync::Arc::from("A")),
        hephaestus::scales::Value::String(std::sync::Arc::from("B")),
        hephaestus::scales::Value::String(std::sync::Arc::from("C")),
        hephaestus::scales::Value::String(std::sync::Arc::from("D")),
    ])
    .range_colors([
        hephaestus::color::rgb(0.20, 0.20, 0.20),
        hephaestus::color::rgb(0.70, 0.20, 0.20),
        hephaestus::color::rgb(0.20, 0.60, 0.20),
        hephaestus::color::rgb(0.20, 0.20, 0.70),
    ]);

    // Left-align the title so its left edge anchors visibly differ
    // between the two `AlignTo` modes — under `Plot` it lands at
    // the left edge of the legend / plot interior; under `Panel`
    // it lands at the left edge of the panel itself. Mutating
    // `plot_title` in place (rather than constructing a new
    // `Element::Set(...)`) preserves the existing 16pt-bold styling
    // from `Theme::default`.
    let mut theme = Theme {
        plot_text_align_to: AlignTo::Plot,
        ..Theme::default()
    };
    if let Element::Set(t) = &mut theme.plot_title {
        t.align = Some(HAlign::Start);
    }
    let mut view = PlotComposition::new(&comp())
        .add_scale("x_scale", scale::continuous(0.0..=6.0))
        .add_scale("y_scale", scale::continuous(0.0..=1.0))
        .add_scale("category", category_scale)
        .theme(theme);
    view.attach_plot(make_plot(
        "a",
        "AlignTo::Plot — title left-edge aligns to plot interior",
    ));
    // Second plot uses a per-plot theme override to flip to Panel.
    view.attach_plot(
        make_plot("b", "AlignTo::Panel — title left-edge aligns to panel").theme_override(
            hephaestus::plot::theme::ThemePart {
                plot_text_align_to: Some(AlignTo::Panel),
                ..hephaestus::plot::theme::ThemePart::default()
            },
        ),
    );

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    let bg: Color = rgb8(245, 245, 245);
    {
        let scene = renderer.scene();
        scene.clear();
        view.render(scene, Size::new(w as f64, h as f64), dpi);
    }
    let mut pixels = vec![0u8; (w * h * 4) as usize];
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");
    let path = std::env::current_dir()
        .unwrap()
        .join("examples/theme_text_align_to.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());
}

examples/theme_plot_background.rs (line 91)

fn main() {
    let (w, h) = (900u32, 600u32);
    let dpi = 96.0;

    let comp = || Composition::empty(1, 1).place(1, 1, Span::cell(), Patch::new("p"));
    // Generate data that explicitly reaches the corners so the
    // rounded clip is visibly exercised. The dense corner clusters
    // get cropped by the rounded panel boundary.
    let mut xs: Vec<f64> = Vec::new();
    let mut ys: Vec<f64> = Vec::new();
    for i in 0..40 {
        let t = i as f64 / 39.0;
        xs.push(t * 6.0);
        ys.push((t * 4.4).sin() * 0.4 + 0.5);
    }
    // Add a corner-hugging cluster at all four corners to make clip
    // behaviour visible.
    for (cx, cy) in &[(0.05, 0.97), (5.95, 0.97), (0.05, 0.03), (5.95, 0.03)] {
        for di in 0..8 {
            let theta = di as f64 * 0.3;
            xs.push(cx + theta.cos() * 0.15);
            ys.push(cy + theta.sin() * 0.04);
        }
    }

    // Use the y values themselves as the colour-mapped channel so a
    // colorbar legend makes sense.
    let colours: Vec<f64> = ys.clone();
    // A second, discrete category column (assigned by x bucket),
    // used to drive the categorical stroke colour and a discrete
    // legend on the right next to the colorbar.
    let categories: Vec<&str> = xs
        .iter()
        .map(|x| match (*x as usize) % 4 {
            0 => "A",
            1 => "B",
            2 => "C",
            _ => "D",
        })
        .collect();
    let mut plot = Plot::new(&comp(), "p")
        .bind("x", "x_scale")
        .bind("y", "y_scale")
        .bind("fill", "fill_scale")
        .bind("stroke", "stroke_scale")
        .title("Rounded corners — plot bg, panel bg, frames");
    plot.add_geom(
        PointGeom::builder()
            .set("x", xs)
            .set("y", ys)
            .set("size", 8.0_f64)
            .set("fill", colours)
            .set("stroke", categories)
            .set("linewidth", 1.0_f64)
            .build(),
    );
    plot.add_axis(Axis::rail(
        "x_scale",
        AxisPlacement::Cartesian(AxisSide::Bottom),
    ));
    plot.add_axis(Axis::rail(
        "y_scale",
        AxisPlacement::Cartesian(AxisSide::Left),
    ));
    plot.add_legend(
        Legend::colorbar("fill_scale")
            .side(LegendSide::Right)
            .title("Amplitude"),
    );
    plot.add_legend(
        Legend::new("stroke_scale")
            .side(LegendSide::Right)
            .title("Group")
            .key(LegendKeySpec::point().scaled("stroke", "stroke_scale")),
    );

    // Two outer bands: 24pt `plot_margin` sits outside the
    // background; 18pt `plot_padding` sits inside it. Both feed the
    // anatomical ring tracks, so chrome lands in the correct rhythm
    // automatically.
    let theme = Theme {
        plot_margin: Margin::all(Length::Abs(24.0)),
        plot_padding: Margin::all(Length::Abs(18.0)),
        plot_background: Element::Set(RectElement {
            fill: Some(ThemeColor::mix(ThemeColor::Paper, ThemeColor::Accent, 0.3)),
            color: Some(ThemeColor::Ink),
            linewidth_pt: Some(Length::Abs(2.0)),
            corner_radius: Some(Length::Abs(12.0)),
            ..RectElement::default()
        }),
        // Round the panel corners too — the geom clip mask uses the
        // same rounded path so data points crop cleanly.
        panel_background: Element::Set(RectElement {
            corner_radius: Some(Length::Abs(8.0)),
            ..Theme::default().panel_background.as_set().unwrap().clone()
        }),
        // Colorbar bar + discrete key frames share `RectElement`
        // semantics: fill paints under the inner content (gradient
        // for the colorbar, marker for the key) so transparent
        // colours show the frame fill; stroke + corner_radius paint
        // on top.
        legend: hephaestus::plot::theme::LegendTheme {
            bar: hephaestus::plot::theme::BarTheme {
                frame: Element::Set(RectElement {
                    fill: Some(ThemeColor::mix(ThemeColor::Paper, ThemeColor::Ink, 0.08)),
                    color: Some(ThemeColor::Ink),
                    linewidth_pt: Some(Length::Abs(1.5)),
                    corner_radius: Some(Length::Abs(6.0)),
                    ..RectElement::default()
                }),
                ..hephaestus::plot::theme::BarTheme::default()
            },
            key: hephaestus::plot::theme::KeyTheme {
                width: Length::Abs(20.0),
                height: Length::Abs(20.0),
                frame: Element::Set(RectElement {
                    fill: Some(ThemeColor::mix(ThemeColor::Paper, ThemeColor::Ink, 0.08)),
                    color: Some(ThemeColor::Ink),
                    linewidth_pt: Some(Length::Abs(0.75)),
                    corner_radius: Some(Length::Abs(4.0)),
                    ..RectElement::default()
                }),
                ..hephaestus::plot::theme::KeyTheme::default()
            },
            ..Theme::default().legend
        },
        ..Theme::default()
    };

    let fill_scale = scale::continuous(0.0..=1.0).range_colors([
        hephaestus::color::rgb(0.2, 0.3, 0.6),
        hephaestus::color::rgb(0.85, 0.45, 0.2),
    ]);
    let stroke_scale = scale::discrete([
        hephaestus::scales::Value::String(std::sync::Arc::from("A")),
        hephaestus::scales::Value::String(std::sync::Arc::from("B")),
        hephaestus::scales::Value::String(std::sync::Arc::from("C")),
        hephaestus::scales::Value::String(std::sync::Arc::from("D")),
    ])
    .range_colors([
        hephaestus::color::rgb(0.20, 0.20, 0.20),
        hephaestus::color::rgb(0.70, 0.20, 0.20),
        hephaestus::color::rgb(0.20, 0.60, 0.20),
        hephaestus::color::rgb(0.20, 0.20, 0.70),
    ]);
    let mut view = PlotComposition::new(&comp())
        .add_scale("x_scale", scale::continuous(0.0..=6.0))
        .add_scale("y_scale", scale::continuous(0.0..=1.0))
        .add_scale("fill_scale", fill_scale)
        .add_scale("stroke_scale", stroke_scale)
        .theme(theme);
    view.attach_plot(plot);

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    // Contrasting canvas bg makes the plot_margin band visible
    // outside the (warm-cream) plot_background.
    let bg: Color = rgb8(60, 70, 90);
    {
        let scene = renderer.scene();
        scene.clear();
        view.render(scene, Size::new(w as f64, h as f64), dpi);
    }
    let mut pixels = vec![0u8; (w * h * 4) as usize];
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");
    let path = std::env::current_dir()
        .unwrap()
        .join("examples/theme_plot_background.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());
}

examples/legends.rs (line 99)

fn main() {
    let (w, h) = (900u32, 600u32);
    let dpi = 96.0;

    // ── Data ──
    let n = 24;
    let xs: Vec<f64> = (0..n).map(|i| i as f64 * 0.4).collect();
    let ys: Vec<f64> = (0..n)
        .map(|i| ((i as f64) * 0.5).sin() * 0.4 + 0.5)
        .collect();
    let cats: [&'static str; 4] = ["A", "B", "C", "D"];
    let fill_col: Vec<&'static str> = (0..n).map(|i| cats[i % 4]).collect();
    let size_col: Vec<&'static str> = (0..n).map(|i| cats[i % 4]).collect();

    // Build the plot's shape registry with the built-in vector
    // shapes plus a handful of emoji glyphs used by the binned
    // legend below. Glyph shapes share the same registry surface
    // as the vector ones (insert by name; look up by name) so the
    // legend chrome can resolve either.
    let glyph_style = TextStyle::new(16.0);
    let mut shapes = ShapeRegistry::with_builtins();
    // U+1F4A7 droplet, U+1F31E sun, U+1F525 fire, U+1F33F herb,
    // U+1F30A wave — picked to read as a "low → high" intensity
    // ramp matching the gradient_scale values.
    shapes.insert("droplet", glyph_marker("\u{1F4A7}", &glyph_style));
    shapes.insert("herb", glyph_marker("\u{1F33F}", &glyph_style));
    shapes.insert("sun", glyph_marker("\u{1F31E}", &glyph_style));
    shapes.insert("wave", glyph_marker("\u{1F30A}", &glyph_style));
    shapes.insert("fire", glyph_marker("\u{1F525}", &glyph_style));

    let mut p = Plot::new(&comp(), "panel")
        .bind("x", "x")
        .bind("y", "y")
        .bind("fill", "category_color")
        .bind("size", "category_size")
        .shape_registry(shapes);
    p.add_geom(
        PointGeom::builder()
            .set("x", xs)
            .set("y", ys)
            .set("fill", fill_col)
            .set("size", size_col)
            .build(),
    );
    p.add_axis(Axis::rail("x", AxisPlacement::Cartesian(AxisSide::Bottom)));
    p.add_axis(Axis::rail("y", AxisPlacement::Cartesian(AxisSide::Left)));

    // ── Right side, legend #1: line + point, both driven by
    // category_color. Attached as two legends; they share a side,
    // title and domain scale, so the render-time collapse folds the
    // second one's key into the first.
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Right)
            .title("Category")
            .key(LegendKeySpec::line().scaled("stroke", "category_color")),
    );
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Right)
            .title("Category")
            .key(
                LegendKeySpec::point()
                    .scaled("fill", "category_color")
                    .fixed("stroke", Value::Color(rgb(0.0, 0.0, 0.0)))
                    .fixed("size", 6.0_f64),
            ),
    );

    // ── Right side, legend #2 (stacks below #1): a size legend that
    // shares the Right slot. `category_size` is trained to the same
    // categories as `category_color`, so what keeps this a block of
    // its own is the differing title; the per-side stacker then
    // arranges both legends vertically.
    p.add_legend(
        Legend::new("category_size")
            .side(LegendSide::Right)
            .title("Size")
            .key(
                LegendKeySpec::point()
                    .scaled("size", "category_size")
                    .fixed("fill", Value::Color(rgb(0.25, 0.25, 0.25))),
            ),
    );

    // ── Right side, legend #3: a continuous gradient colorbar
    // driven by `gradient_scale`. Stacks below the discrete ones
    // via the same per-side stacker. The colorbar also pulls its
    // opacity from `gradient_opacity` — same domain → low values are
    // mostly transparent, high values fully opaque.
    p.add_legend(
        Legend::colorbar("gradient_scale")
            .side(LegendSide::Right)
            .title("Gradient")
            .scaled("fill_opacity", "gradient_opacity"),
    );

    // ── Bottom side, legend #3: same gradient scale but rendered
    // as discrete steps at each break — useful for showing a
    // binned colour mapping or any colorbar you want to read as
    // categorical bands. Routed to the Bottom slot so it stacks
    // horizontally alongside the existing "Pattern" + "Colour"
    // legends.
    p.add_legend(
        Legend::colorbar("gradient_scale")
            .side(LegendSide::Bottom)
            .title("Steps")
            .binned()
            .open_upper(),
    );

    // ── Bottom side, legend #4: a **binned stack** that varies
    // SHAPE per bin (instead of colour like the stepped colorbar
    // next to it). Six bin boundaries from `gradient_scale` → five
    // bins, each rendered as a different emoji-glyph shape via the
    // `bin_shape` scale (resolved against the plot's shape
    // registry). Demonstrates that the same legend key wiring
    // works with vector and glyph-backed shapes.
    //
    // Emoji glyphs fill their em-bbox almost completely (Latin
    // letters and vector circles only fill ~70–80 % of the same
    // bbox), so a 12pt emoji reads at roughly the same visual
    // weight as the 16pt circle markers used by the other legends.
    p.add_legend(
        Legend::new("gradient_scale")
            .side(LegendSide::Bottom)
            .title("Bins")
            .binned()
            .equal_bins()
            .key(
                LegendKeySpec::point()
                    .scaled("shape", "bin_shape")
                    .fixed("fill", Value::Color(rgb(0.15, 0.15, 0.15)))
                    .fixed("size", 12.0_f64),
            ),
    );

    // ── Left side: a text key. The swatch is a glyph sample rather
    // than a marker, so a font-size scale shows what it actually
    // does to type. `size` is the font size in pt and `fill` is the
    // ink; both resolve per row through their own scale.
    p.add_legend(
        Legend::new("category_size")
            .side(LegendSide::Left)
            .title("Font size")
            .key(
                LegendKeySpec::text()
                    .scaled("size", "category_size")
                    .scaled("fill", "category_color")
                    .fixed("text", Value::String(Arc::from("Aa"))),
            ),
    );

    // ── Bottom side: two legends side-by-side (horizontal stack).
    p.add_legend(
        Legend::new("category_line")
            .side(LegendSide::Bottom)
            .title("Pattern")
            .key(
                LegendKeySpec::line()
                    .scaled("linetype", "category_line")
                    .fixed("linewidth", 1.5_f64),
            ),
    );
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Bottom)
            .title("Colour")
            .key(LegendKeySpec::rect().scaled("fill", "category_color")),
    );

    // ── In-panel overlay: a compact category legend pinned to the
    // top-right corner of the panel area. Reserves no chrome space —
    // the data marks beneath continue to occupy the full panel rect.
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::InPanel {
                anchor: Anchor::TopRight,
                inset_pt: 8.0,
            })
            .title("Overlay")
            .key(
                LegendKeySpec::point()
                    .scaled("fill", "category_color")
                    .fixed("size", 6.0_f64),
            ),
    );

    let cat_values: Vec<Value> = cats.iter().map(|s| Value::String(Arc::from(*s))).collect();
    let line_cats: [&'static str; 3] = ["Solid", "Dashed", "Dotted"];
    let line_values: Vec<Value> = line_cats
        .iter()
        .map(|s| Value::String(Arc::from(*s)))
        .collect();

    let mut view = PlotComposition::new(&comp())
        .add_scale("x", scale::continuous(0.0..=10.0))
        .add_scale("y", scale::continuous(0.0..=1.0))
        .add_scale(
            "category_color",
            scale::discrete(cat_values.clone()).range_colors([
                rgb8(220, 90, 70),
                rgb8(70, 160, 90),
                rgb8(70, 120, 220),
                rgb8(180, 120, 200),
            ]),
        )
        .add_scale(
            "category_size",
            scale::discrete(cat_values).range_numbers([4.0, 8.0, 12.0, 16.0]),
        )
        .add_scale(
            "category_line",
            scale::discrete(line_values).range_linetypes([solid(), dashed(), dotted()]),
        )
        .add_scale(
            "gradient_scale",
            scale::continuous(0.0..=100.0).range_colors([
                rgb8(20, 30, 90),
                rgb8(60, 160, 200),
                rgb8(230, 220, 100),
                rgb8(220, 60, 40),
            ]),
        )
        .add_scale(
            "gradient_opacity",
            scale::continuous(0.0..=100.0).range_numbers([0.1, 1.0]),
        )
        .add_scale(
            "bin_shape",
            scale::continuous(0.0..=100.0).range_strings([
                Arc::from("droplet"),
                Arc::from("herb"),
                Arc::from("sun"),
                Arc::from("wave"),
                Arc::from("fire"),
            ]),
        );
    view.attach_plot(p);

    let issues = view.validate();
    if !issues.is_empty() {
        panic!("validate(): {issues:?}");
    }

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    let bg: Color = rgb8(252, 252, 252);
    {
        let scene = renderer.scene();
        scene.clear();
        view.render(scene, Size::new(w as f64, h as f64), dpi);
    }
    let mut pixels = vec![0u8; (w * h * 4) as usize];
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");
    let path = std::env::current_dir()
        .unwrap()
        .join("examples/legends.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());
}

pub fn fixed( self, aesthetic: impl Into<String>, value: impl Into<Value>, ) -> Self

Pin this aesthetic to a fixed value across every row.

Examples found in repository

examples/theme_legend_variants.rs (line 62)

fn main() {
    let (w, h) = (900u32, 600u32);
    let dpi = 96.0;

    let n = 24;
    let xs: Vec<f64> = (0..n).map(|i| i as f64 * 0.4).collect();
    let ys: Vec<f64> = (0..n)
        .map(|i| ((i as f64) * 0.5).sin() * 0.4 + 0.5)
        .collect();
    let cats: [&'static str; 4] = ["A", "B", "C", "D"];
    let fill_col: Vec<&'static str> = (0..n).map(|i| cats[i % 4]).collect();

    let mut plot = Plot::new(&comp(), "panel")
        .bind("x", "x")
        .bind("y", "y")
        .bind("fill", "category_color")
        .title("Two legends, one opts into the \"hero\" theme variant");
    plot.add_geom(
        PointGeom::builder()
            .set("x", xs)
            .set("y", ys)
            .set("fill", fill_col.clone())
            .set("size", 6.0_f64)
            .build(),
    );
    plot.add_axis(Axis::rail("x", AxisPlacement::Cartesian(AxisSide::Bottom)));
    plot.add_axis(Axis::rail("y", AxisPlacement::Cartesian(AxisSide::Left)));

    // First legend — opts into the "hero" variant.
    plot.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Right)
            .title("Category (hero)")
            .theme_variant("hero")
            .key(
                LegendKeySpec::point()
                    .scaled("fill", "category_color")
                    .fixed("stroke", Value::Color(rgb(0.0, 0.0, 0.0)))
                    .fixed("size", 6.0_f64),
            ),
    );
    // Second legend — uses the default LegendTheme.
    plot.add_legend(
        Legend::new("category_size")
            .side(LegendSide::Bottom)
            .title("Category (default)")
            .key(
                LegendKeySpec::point()
                    .scaled("fill", "category_color")
                    .fixed("size", 6.0_f64),
            ),
    );

    // Register a "hero" variant on the theme. Distinct background
    // tint + a denser margin to telegraph the emphasis.
    let hero = LegendTheme {
        background: Element::Set(RectElement {
            fill: Some(ThemeColor::mix(ThemeColor::Paper, ThemeColor::Accent, 0.18)),
            color: Some(ThemeColor::Accent),
            linewidth_pt: Some(Length::Abs(1.0)),
            ..RectElement::default()
        }),
        ..LegendTheme::default()
    };

    let theme = Theme::default().with_legend_variant("hero", hero);

    let mut view = PlotComposition::new(&comp())
        .add_scale("x", scale::continuous(0.0..=12.0))
        .add_scale("y", scale::continuous(0.0..=1.0))
        .add_scale(
            "category_color",
            scale::discrete(cats.iter().map(|s| Value::String((*s).into()))).range_colors([
                rgb8(220, 100, 80),
                rgb8(80, 160, 100),
                rgb8(80, 130, 200),
                rgb8(180, 100, 200),
            ]),
        )
        .add_scale(
            "category_size",
            scale::discrete(cats.iter().map(|s| Value::String((*s).into())))
                .range_numbers([4.0, 6.0, 8.0, 10.0]),
        )
        .theme(theme);
    view.attach_plot(plot);

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    let bg: Color = rgb8(252, 252, 252);
    {
        let scene = renderer.scene();
        scene.clear();
        view.render(scene, Size::new(w as f64, h as f64), dpi);
    }
    let mut pixels = vec![0u8; (w * h * 4) as usize];
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");
    let path = std::env::current_dir()
        .unwrap()
        .join("examples/theme_legend_variants.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());
}

examples/faceted.rs (line 108)

fn main() {
    let (w, h) = (1400u32, 700u32);
    let dpi = 96.0;

    let xs: Vec<f64> = (0..50).map(|i| i as f64 * 2.0).collect();
    let make = |phase: f64, amp: f64| -> Vec<f64> {
        xs.iter()
            .map(|x| 50.0 + amp * (x * 0.05 + phase).sin())
            .collect()
    };

    let datasets = [
        ("q1", make(0.0, 25.0), rgb8(220, 90, 70)),
        ("q2", make(1.5, 18.0), rgb8(70, 120, 220)),
        ("q3", make(3.0, 22.0), rgb8(70, 180, 120)),
        ("q4", make(4.5, 28.0), rgb8(180, 130, 80)),
        ("summary", make(0.0, 35.0), rgb8(130, 80, 180)),
    ];

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    let bg: Color = rgb8(248, 248, 252);

    // ── Renders 1 & 2: shared "time" scale across the unlocked layout
    {
        #[allow(unused_mut)]
        let mut view = PlotComposition::new(&comp_shape(None))
            .add_scale("time", scale::continuous(0.0..=100.0))
            .add_scale("y", scale::continuous(0.0..=100.0))
            .title("Sensor array")
            .subtitle("Four quadrants and a summary, sharing one time scale")
            .caption("Composition-level chrome spans every panel");
        attach_all(&mut view, &xs, &datasets);

        // One axis title and one legend for the whole grid, set on the
        // composition rather than on any single plot. The legend reads
        // its rows from the "series" scale's domain; no plot needs to
        // bind that scale for the legend to resolve it.
        let mut view = {
            let series: Vec<Value> = datasets.iter().map(|(id, _, _)| Value::from(*id)).collect();
            let colors: Vec<Color> = datasets.iter().map(|(_, _, c)| *c).collect();
            let mut view = view
                .add_scale("series", scale::discrete(series).range_colors(colors))
                .axis_title(AxisSide::Bottom, "Time (s)");
            view.add_legend(
                Legend::new("series")
                    .side(LegendSide::Right)
                    .title("Series")
                    .key(
                        LegendKeySpec::point()
                            .scaled("fill", "series")
                            .fixed("size", 6.0_f64),
                    ),
            );
            view
        };

        let issues = view.validate();
        if !issues.is_empty() {
            panic!("validate() reported issues: {issues:?}");
        }

        render_to(
            &mut renderer,
            &mut view,
            w,
            h,
            dpi,
            bg,
            "examples/faceted_1_initial.png",
        );

        view.update_scale("time", |s| s.set_domain_continuous(20.0, 60.0));
        render_to(
            &mut renderer,
            &mut view,
            w,
            h,
            dpi,
            bg,
            "examples/faceted_2_shared_zoom.png",
        );
    }

    // ── Render 3: aspect-locked. Outer `.aspect(1, 1)` propagates to
    //    every leaf panel; selective respect on the layout solver
    //    couples panel col/row at the locked ratio and lets unmarked
    //    fr tracks absorb slack. Wider viewport (1800×600) makes the
    //    lock visually obvious — without it, the 1×2 outer would give
    //    half the width to each side; with it, the leaf panels land
    //    at the locked ratio and the surrounding tracks soak up the
    //    horizontal slack.
    {
        let (lw, lh) = (1800u32, 600u32);
        let mut view = PlotComposition::new(&comp_shape(Some((1.0, 1.0))))
            .add_scale("time", scale::continuous(20.0..=60.0))
            .add_scale("y", scale::continuous(0.0..=100.0));
        attach_all(&mut view, &xs, &datasets);
        render_to(
            &mut renderer,
            &mut view,
            lw,
            lh,
            dpi,
            bg,
            "examples/faceted_3_aspect_locked.png",
        );
    }
}

examples/legends.rs (line 108)

fn main() {
    let (w, h) = (900u32, 600u32);
    let dpi = 96.0;

    // ── Data ──
    let n = 24;
    let xs: Vec<f64> = (0..n).map(|i| i as f64 * 0.4).collect();
    let ys: Vec<f64> = (0..n)
        .map(|i| ((i as f64) * 0.5).sin() * 0.4 + 0.5)
        .collect();
    let cats: [&'static str; 4] = ["A", "B", "C", "D"];
    let fill_col: Vec<&'static str> = (0..n).map(|i| cats[i % 4]).collect();
    let size_col: Vec<&'static str> = (0..n).map(|i| cats[i % 4]).collect();

    // Build the plot's shape registry with the built-in vector
    // shapes plus a handful of emoji glyphs used by the binned
    // legend below. Glyph shapes share the same registry surface
    // as the vector ones (insert by name; look up by name) so the
    // legend chrome can resolve either.
    let glyph_style = TextStyle::new(16.0);
    let mut shapes = ShapeRegistry::with_builtins();
    // U+1F4A7 droplet, U+1F31E sun, U+1F525 fire, U+1F33F herb,
    // U+1F30A wave — picked to read as a "low → high" intensity
    // ramp matching the gradient_scale values.
    shapes.insert("droplet", glyph_marker("\u{1F4A7}", &glyph_style));
    shapes.insert("herb", glyph_marker("\u{1F33F}", &glyph_style));
    shapes.insert("sun", glyph_marker("\u{1F31E}", &glyph_style));
    shapes.insert("wave", glyph_marker("\u{1F30A}", &glyph_style));
    shapes.insert("fire", glyph_marker("\u{1F525}", &glyph_style));

    let mut p = Plot::new(&comp(), "panel")
        .bind("x", "x")
        .bind("y", "y")
        .bind("fill", "category_color")
        .bind("size", "category_size")
        .shape_registry(shapes);
    p.add_geom(
        PointGeom::builder()
            .set("x", xs)
            .set("y", ys)
            .set("fill", fill_col)
            .set("size", size_col)
            .build(),
    );
    p.add_axis(Axis::rail("x", AxisPlacement::Cartesian(AxisSide::Bottom)));
    p.add_axis(Axis::rail("y", AxisPlacement::Cartesian(AxisSide::Left)));

    // ── Right side, legend #1: line + point, both driven by
    // category_color. Attached as two legends; they share a side,
    // title and domain scale, so the render-time collapse folds the
    // second one's key into the first.
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Right)
            .title("Category")
            .key(LegendKeySpec::line().scaled("stroke", "category_color")),
    );
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Right)
            .title("Category")
            .key(
                LegendKeySpec::point()
                    .scaled("fill", "category_color")
                    .fixed("stroke", Value::Color(rgb(0.0, 0.0, 0.0)))
                    .fixed("size", 6.0_f64),
            ),
    );

    // ── Right side, legend #2 (stacks below #1): a size legend that
    // shares the Right slot. `category_size` is trained to the same
    // categories as `category_color`, so what keeps this a block of
    // its own is the differing title; the per-side stacker then
    // arranges both legends vertically.
    p.add_legend(
        Legend::new("category_size")
            .side(LegendSide::Right)
            .title("Size")
            .key(
                LegendKeySpec::point()
                    .scaled("size", "category_size")
                    .fixed("fill", Value::Color(rgb(0.25, 0.25, 0.25))),
            ),
    );

    // ── Right side, legend #3: a continuous gradient colorbar
    // driven by `gradient_scale`. Stacks below the discrete ones
    // via the same per-side stacker. The colorbar also pulls its
    // opacity from `gradient_opacity` — same domain → low values are
    // mostly transparent, high values fully opaque.
    p.add_legend(
        Legend::colorbar("gradient_scale")
            .side(LegendSide::Right)
            .title("Gradient")
            .scaled("fill_opacity", "gradient_opacity"),
    );

    // ── Bottom side, legend #3: same gradient scale but rendered
    // as discrete steps at each break — useful for showing a
    // binned colour mapping or any colorbar you want to read as
    // categorical bands. Routed to the Bottom slot so it stacks
    // horizontally alongside the existing "Pattern" + "Colour"
    // legends.
    p.add_legend(
        Legend::colorbar("gradient_scale")
            .side(LegendSide::Bottom)
            .title("Steps")
            .binned()
            .open_upper(),
    );

    // ── Bottom side, legend #4: a **binned stack** that varies
    // SHAPE per bin (instead of colour like the stepped colorbar
    // next to it). Six bin boundaries from `gradient_scale` → five
    // bins, each rendered as a different emoji-glyph shape via the
    // `bin_shape` scale (resolved against the plot's shape
    // registry). Demonstrates that the same legend key wiring
    // works with vector and glyph-backed shapes.
    //
    // Emoji glyphs fill their em-bbox almost completely (Latin
    // letters and vector circles only fill ~70–80 % of the same
    // bbox), so a 12pt emoji reads at roughly the same visual
    // weight as the 16pt circle markers used by the other legends.
    p.add_legend(
        Legend::new("gradient_scale")
            .side(LegendSide::Bottom)
            .title("Bins")
            .binned()
            .equal_bins()
            .key(
                LegendKeySpec::point()
                    .scaled("shape", "bin_shape")
                    .fixed("fill", Value::Color(rgb(0.15, 0.15, 0.15)))
                    .fixed("size", 12.0_f64),
            ),
    );

    // ── Left side: a text key. The swatch is a glyph sample rather
    // than a marker, so a font-size scale shows what it actually
    // does to type. `size` is the font size in pt and `fill` is the
    // ink; both resolve per row through their own scale.
    p.add_legend(
        Legend::new("category_size")
            .side(LegendSide::Left)
            .title("Font size")
            .key(
                LegendKeySpec::text()
                    .scaled("size", "category_size")
                    .scaled("fill", "category_color")
                    .fixed("text", Value::String(Arc::from("Aa"))),
            ),
    );

    // ── Bottom side: two legends side-by-side (horizontal stack).
    p.add_legend(
        Legend::new("category_line")
            .side(LegendSide::Bottom)
            .title("Pattern")
            .key(
                LegendKeySpec::line()
                    .scaled("linetype", "category_line")
                    .fixed("linewidth", 1.5_f64),
            ),
    );
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::Bottom)
            .title("Colour")
            .key(LegendKeySpec::rect().scaled("fill", "category_color")),
    );

    // ── In-panel overlay: a compact category legend pinned to the
    // top-right corner of the panel area. Reserves no chrome space —
    // the data marks beneath continue to occupy the full panel rect.
    p.add_legend(
        Legend::new("category_color")
            .side(LegendSide::InPanel {
                anchor: Anchor::TopRight,
                inset_pt: 8.0,
            })
            .title("Overlay")
            .key(
                LegendKeySpec::point()
                    .scaled("fill", "category_color")
                    .fixed("size", 6.0_f64),
            ),
    );

    let cat_values: Vec<Value> = cats.iter().map(|s| Value::String(Arc::from(*s))).collect();
    let line_cats: [&'static str; 3] = ["Solid", "Dashed", "Dotted"];
    let line_values: Vec<Value> = line_cats
        .iter()
        .map(|s| Value::String(Arc::from(*s)))
        .collect();

    let mut view = PlotComposition::new(&comp())
        .add_scale("x", scale::continuous(0.0..=10.0))
        .add_scale("y", scale::continuous(0.0..=1.0))
        .add_scale(
            "category_color",
            scale::discrete(cat_values.clone()).range_colors([
                rgb8(220, 90, 70),
                rgb8(70, 160, 90),
                rgb8(70, 120, 220),
                rgb8(180, 120, 200),
            ]),
        )
        .add_scale(
            "category_size",
            scale::discrete(cat_values).range_numbers([4.0, 8.0, 12.0, 16.0]),
        )
        .add_scale(
            "category_line",
            scale::discrete(line_values).range_linetypes([solid(), dashed(), dotted()]),
        )
        .add_scale(
            "gradient_scale",
            scale::continuous(0.0..=100.0).range_colors([
                rgb8(20, 30, 90),
                rgb8(60, 160, 200),
                rgb8(230, 220, 100),
                rgb8(220, 60, 40),
            ]),
        )
        .add_scale(
            "gradient_opacity",
            scale::continuous(0.0..=100.0).range_numbers([0.1, 1.0]),
        )
        .add_scale(
            "bin_shape",
            scale::continuous(0.0..=100.0).range_strings([
                Arc::from("droplet"),
                Arc::from("herb"),
                Arc::from("sun"),
                Arc::from("wave"),
                Arc::from("fire"),
            ]),
        );
    view.attach_plot(p);

    let issues = view.validate();
    if !issues.is_empty() {
        panic!("validate(): {issues:?}");
    }

    let mut renderer = VelloRenderer::new().expect("vello renderer init");
    let bg: Color = rgb8(252, 252, 252);
    {
        let scene = renderer.scene();
        scene.clear();
        view.render(scene, Size::new(w as f64, h as f64), dpi);
    }
    let mut pixels = vec![0u8; (w * h * 4) as usize];
    renderer
        .render_to_buffer(w, h, bg, &mut pixels)
        .expect("render");
    let path = std::env::current_dir()
        .unwrap()
        .join("examples/legends.png");
    hephaestus::image::write_png(&path, w, h, &pixels).expect("write png");
    println!("wrote {}", path.display());
}

Trait Implementations

impl Clone for LegendKeySpec

fn clone(&self) -> LegendKeySpec

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LegendKeySpec

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.