Skip to main content

Crate kuva

Crate kuva 

Source
Expand description

Scientific plotting library for bioinformatics, targeting SVG output with optional PNG and PDF backends.

§Pipeline

plot definition  →  Layout  →  Scene (primitives)  →  backend output
  1. Build a plot struct using its builder API (e.g. plot::scatter::ScatterPlot).
  2. Collect plots into a Vec<render::plots::Plot> — use .into() on any plot struct.
  3. Build a render::layout::Layout with render::layout::Layout::auto_from_plots and customise it.
  4. Call render_to_svg (or render_to_png / render_to_pdf) to get the output in one step.

§Example

use kuva::prelude::*;

let scatter = ScatterPlot::new()
    .with_data(vec![(1.0_f64, 2.0), (3.0, 4.0)])
    .with_color("steelblue");

let plots: Vec<Plot> = vec![scatter.into()];
let svg = kuva::render_to_svg(plots, Layout::auto_from_plots(&[]));
assert!(svg.contains("<svg"));

§Feature flags

FeatureDescription
pngEnables RasterBackend (direct pixel-buffer rasteriser) and the PngBackend compatibility shim.
pdfEnables PdfBackend for vector PDF output via krilla. Requires Rust >= 1.92 (higher than the crate’s own MSRV — see CHANGELOG.md).
embed_fontEnables backend::svg::SvgBackend::with_embedded_font — bakes DejaVu Sans into the SVG as a base64 @font-face. Adds flate2 as a dependency but does not pull in png or pdf.
cliEnables the kuva CLI binary (pulls in clap).
typst-mathTypesets $...$ labels with the Typst compiler (linked as a library) for real 2-D math in SVG/PNG/PDF. Heavy (~200 crates) and opt-in: deliberately not in full. Requires Rust >= 1.89.
typstEnables TypstBackend for emitting Typst markup (compile externally). Zero deps, but opt-in — also not in full.
fullEnables embed_font + png + pdf — the core backends for the expected use cases. Extras (typst-math, typst, parquet, emit_code) are opted into explicitly.

§Math in labels

Any label (title, axis labels, annotations, markdown body text) may contain $...$ math regions written in LaTeX-ish syntax: $\sigma^2$, $\frac{a}{b}$, $\sqrt{x^2 + y^2}$. There are two rendering tiers:

  • Lookup tier (always available, zero deps): math is lowered to inline Unicode — Greek letters, operators, super/subscripts, \frac→a/b, \sqrt→√(…). Every backend without typst-math uses this, and it is the only tier the terminal backend can use. Write a literal dollar as \$. See render::math::to_unicode.
  • Typst tier (feature typst-math): the whole label is typeset by the Typst compiler (linked as a library) for real 2-D math (stacked fractions, radicals with vinculum, large operators) and embedded into SVG/PNG/PDF output. Opt-in and excluded from full: it pulls a ~200-crate dependency tree and needs Rust >= 1.89, so it is enabled explicitly (--features typst-math,png) rather than riding a broader feature.

Note: Typst math is not LaTeX — a multi-letter run like mc is one identifier, so write $E = m c^2$, not $E = mc^2$.

§Fonts

DejaVu Sans is bundled inside the crate. The PNG and PDF backends always load it before scanning system fonts, so text renders correctly even in minimal environments (containers, CI pipelines) with no installed fonts.

SVG output references fonts by name and relies on the viewer to resolve them. For self-contained SVGs that work anywhere, use backend::svg::SvgBackend::with_embedded_font or the --embed-font CLI flag. This bakes DejaVu Sans as a base64 @font-face block into the SVG at the cost of roughly 1 MB of added file size.

Re-exports§

pub use backend::terminal::TerminalBackend;
pub use backend::png::PngBackend;
pub use backend::raster::RasterBackend;
pub use backend::pdf::PageSize;
pub use backend::pdf::PdfBackend;
pub use backend::typst::TypstBackend;
pub use render::datetime::ymd;
pub use render::datetime::ymd_hms;
pub use render::datetime::DateTimeAxis;
pub use render::datetime::DateUnit;
pub use render::render_utils::silverman_bandwidth;
pub use render::render_utils::simple_kde;
pub use render::layout::AxisLabelOverlap;
pub use render::layout::AxisLine;
pub use render::layout::TickAlign;
pub use render::layout::TickFormat;
pub use render::layout::TickPos;
pub use render::palette::Palette;
pub use render::render::render_calendar;
pub use render::render::render_phylo_tree;
pub use render::render::render_sankey;
pub use render::render::render_synteny;
pub use render::render::render_twin_y;
pub use render::render_utils::simple_kde_reflect;
pub use render::theme::Theme;

Modules§

backend
plot
prelude
Convenience re-exports for the most commonly used types.
render

Constants§

VERSION
The kuva crate version (from Cargo.toml), e.g. "0.6.0". Stamped into rendered output (SVG comment, PNG Software text chunk, PDF creator/producer) so a saved figure records which version produced it.

Functions§

render_to_pdf
Render a collection of plots to a PDF byte vector in one call (requires feature pdf).
render_to_pdf_multi
Render several plot collections to a single multi-page PDF — one page per (plots, layout) pair — in one call (requires feature pdf).
render_to_png
Render a collection of plots to a PNG byte vector in one call (requires feature png).
render_to_raster
Render a collection of plots directly to a PNG byte vector (requires feature png).
render_to_svg
Render a collection of plots to an SVG string in one call.