ruviz

High-performance 2D plotting library for Rust.

Quick Start

Add the crate:

[dependencies]
ruviz = "0.4.20"

Create and save a PNG:

use ruviz::prelude::*;

fn main() -> Result<()> {
    let x: Vec<f64> = (0..100).map(|i| i as f64 * 0.1).collect();
    let y: Vec<f64> = x.iter().map(|&v| v.sin()).collect();

    Plot::new()
        .line(&x, &y)
        .title("Sine Wave")
        .xlabel("x")
        .ylabel("sin(x)")
        .save("sine.png")?;

    Ok(())
}

Run with:

cargo run --release

Common API

The main API is the fluent Plot builder. Series are finalized automatically when you render, save, or start another series.

use ruviz::prelude::*;

fn main() -> Result<()> {
    let x = vec![0.0, 1.0, 2.0, 3.0, 4.0];
    let linear = x.clone();
    let quadratic: Vec<f64> = x.iter().map(|&v| v * v).collect();

    Plot::new()
        .line(&x, &linear)
        .label("Linear")
        .line(&x, &quadratic)
        .label("Quadratic")
        .legend(Position::TopLeft)
        .theme(Theme::publication())
        .save("series.png")?;

    Ok(())
}

Top-level helpers are available for line, scatter, and bar plots:

use ruviz::prelude::*;

fn main() -> Result<()> {
    let x = vec![0.0, 1.0, 2.0];
    let y = vec![0.0, 1.0, 4.0];

    line(&x, &y)
        .title("Line")
        .save("line.png")?;

    Ok(())
}

The ruviz::simple module also provides file-oriented helper functions such as line_plot, scatter_plot, bar_chart, and histogram.

Plot Types

The root Plot builder currently exposes:

• Basic: line, scatter, bar, histogram, box plot, heatmap
• Distribution: KDE, ECDF, violin, boxen
• Composition and polar: pie, donut styling, radar, polar line
• Continuous, discrete, and error plots: contour, area, step, stem, symmetric/asymmetric error bars
• Vector: quiver
• Layout helpers: subplots, legends, grid/tick controls, annotations, insets

Some lower-level modules contain additional experimental plot implementations that do not yet have a high-level Plot::new().type(...) builder method.

Export

• save("plot.png") writes PNG files on native targets.
• render() returns an in-memory Image.
• render_png_bytes() returns PNG bytes.
• export_svg("plot.svg") writes SVG files on native targets.
• render_to_svg() returns an SVG string.
• save_pdf("plot.pdf") is available with the pdf feature.

For browser/wasm targets, use in-memory helpers such as render_png_bytes(), render_to_svg(), and Image::encode_png() instead of native file-path export helpers.

Feature Flags

Default features are ndarray_support and parallel.

SVG export is available without enabling the legacy svg feature.

Backend Notes

.backend(...), .auto_optimize(), and .get_backend_name() store or report backend preference metadata. auto_optimize() conservatively selects Skia rather than advertising a backend that cannot execute across every public raster path. Use .resolved_backend_name() for the native Plot PNG path, or .backend_resolution(...) to inspect the requested backend, actual backend, and any explicit Skia fallback reason for a raster operation. Supported scatter workloads resolve to DataShader only when that backend is explicitly configured.

Use release builds and benchmark your actual workload before adding optional performance features. See Backend Selection and Performance Optimization.

Typst Text Mode

Enable Typst-backed text rendering with:

[dependencies]
ruviz = { version = "0.4.20", features = ["typst-math"] }

Then call .typst(true). The configured family is passed to plain raster, plain SVG, and Typst text. Named-font consistency depends on that font being available to each renderer or SVG viewer; otherwise backend-specific fallback or substitution may occur. Typst resolves serif, sans-serif, and monospace to available concrete families. Because Typst has no generic cursive or fantasy selector, those two values use its selected sans-serif fallback:

use ruviz::prelude::*;

fn main() -> Result<()> {
    let x: Vec<f64> = (0..50).map(|i| i as f64 * 0.1).collect();
    let y: Vec<f64> = x.iter().map(|&v| (-v).exp()).collect();

    Plot::new()
        .line(&x, &y)
        .title("$f(x) = e^(-x)$")
        .xlabel("$x$")
        .ylabel("$f(x)$")
        .font_family("New Computer Modern Sans")
        .typst(true)
        .save("typst_plot.png")?;

    Ok(())
}

Without typst-math, .typst(true) and TextEngineMode::Typst are not compiled. If Typst is optional in your crate, forward and guard your own feature:

[dependencies]
ruviz = { version = "0.4.20", default-features = false }

[features]
default = []
typst-math = ["ruviz/typst-math"]

use ruviz::prelude::*;

fn main() -> Result<()> {
    let x: Vec<f64> = (0..50).map(|i| i as f64 * 0.1).collect();
    let y: Vec<f64> = x.iter().map(|&v| (-v).exp()).collect();

    let mut plot = Plot::new()
        .line(&x, &y)
        .title("$f(x) = e^(-x)$");

    #[cfg(feature = "typst-math")]
    {
        plot = plot.typst(true);
    }

    plot.save("typst_plot.png")?;
    Ok(())
}

Examples

Rust documentation examples are in examples/doc_*.rs.

cargo run --example doc_line_plot
cargo run --example doc_scatter_plot
cargo run --example doc_typst_text --features typst-math

Interactive examples require the interactive feature:

cargo run --features interactive --example basic_interaction
cargo run --features interactive --example interactive_multi_series

Animation examples require the animation feature:

cargo run --features animation --example animation_basic
cargo run --features animation --example animation_wave

Documentation

• Quick Start
• User Guide
• API Documentation
• Gallery

Development

cargo test
cargo test --doc
cargo run --example basic_example --release

The workspace also contains companion crates and bindings, but this README focuses on the root Rust crate. See the subdirectory READMEs for those package surfaces.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE or http://opensource.org/licenses/MIT)

at your option.