Repository files navigation

• Introduction
• Basic Usage
  • Exporting a single Interactive Plot
  • Exporting Static Images with plotly_static (Recommended)
  • Exporting Static Images with Kaleido (legacy)
  • Usage Within a WASM Environment
  • Timeseries Downsampling
• Crate Feature Flags
• Contributing
• Code of Conduct
• License

A plotting library for Rust powered byPlotly.js.

Documentation and numerous interactive examples are available in thePlotly.rs Book, theexamples/ directory anddocs.rs.

For changes since the last version, please consult thechangelog.

Add this to yourCargo.toml:

[dependencies]plotly ="0.13"

Any figure can be saved as an HTML file using thePlot.write_html() method. These HTML files can be opened in any web browser to access the fully interactive figure.

use plotly::{Plot,Scatter};letmut plot =Plot::new();let trace =Scatter::new(vec![0,1,2],vec![2,1,0]);plot.add_trace(trace);plot.write_html("out.html");

By default, the Plotly JavaScript library and someMathJax components will always be included via CDN, which results in smaller file-size, but slightly slower first load as the JavaScript libraries have to be downloaded first. Alternatively, to embed the JavaScript libraries (several megabytes in size) directly into the HTML file,plotly-rs must be compiled with the feature flagplotly_embed_js. With this feature flag the Plotly and MathJax JavaScript libraries are directly embedded in the generated HTML file. It is still possible to use the CDN version, by using theuse_cdn_js method.

// <-- Create a `Plot` -->plot.use_cdn_js();plot.write_html("out.html");

If you only want to view the plot in the browser quickly, use thePlot.show() method.

// <-- Create a `Plot` -->plot.show();// The default web browser will open, displaying an interactive plot

The recommended way to export static images is using theplotly_static backend, which uses a headless browser via WebDriver (Chrome or Firefox) for rendering. This is available via thestatic_export_default feature:

[dependencies]plotly = {version ="0.13",features = ["static_export_default"] }

This supports PNG, JPEG, WEBP, SVG, and PDF formats:

use plotly::{Plot,Scatter,ImageFormat};letmut plot =Plot::new();plot.add_trace(Scatter::new(vec![0,1,2],vec![2,1,0]));plot.write_image("out.png",ImageFormat::PNG,800,600,1.0)?;plot.write_image("out.svg",ImageFormat::SVG,800,600,1.0)?;let base64_data = plot.to_base64(ImageFormat::PNG,800,600,1.0)?;let svg_string = plot.to_svg(800,600,1.0)?;

Note: This feature requires a WebDriver-compatible browser (Chrome or Firefox) as well as a Webdriver (chromedriver/geckodriver) to be available on the system.

The above example uses the legacy API that is backwards compatible with the Kaleido API. However, for more efficient workflows aStaticExporter object can be built and reused between calls towrite_image.

More specifically, enabling any of theplotly featuresstatic_export_chromedriver,static_export_geckodriver, orstatic_export_default gives access to both the synchronousStaticExporter and the asynchronousAsyncStaticExporter (available viaplotly::plotly_static). For exporter reuse and up-to-date sync/async usage patterns, please see the dedicated example inexamples/static_export, which demonstrates both synchronous and asynchronous exporters and how to reuse a single exporter instance across multiple exports.

For further details seeplotly_static crate documentation.

Enable thekaleido feature and opt in for automatic downloading of thekaleido binaries by doing the following

# Cargo.toml[dependencies]plotly = {version ="0.13",features = ["kaleido","kaleido_download"] }

Alternatively, enable only thekaleido feature and manually install Kaleido.

# Cargo.toml[dependencies]plotly = {version ="0.13",features = ["kaleido"] }

With the feature enabled, plots can be saved as any ofpng,jpeg,webp,svg,pdf andeps. Note that the plot will be a static image, i.e. they will be non-interactive.

Exporting a simple plot looks like this:

use plotly::{ImageFormat,Plot};letmut plot =Plot::new();let trace =Scatter::new(vec![0,1,2],vec![2,1,0]);plot.add_trace(trace);plot.write_image("out.png",ImageFormat::PNG,800,600,1.0);

When developing applications for your host, enabling bothkaleido andkaleido_download features will ensure that thekaleido binary is downloaded for your system's architecture at compile time. After download, it is unpacked into a specific path, e.g., on Linux this is/home/USERNAME/.config/kaleido. With these two features enabled, static images can be exported as described in the next section as long as the application runs on the same machine where it has been compiled on.

When the applications developed withplotly.rs are intended for other targets or when the user wants to control where thekaleido binary is installed then Kaleido must be manually downloaded and installed. Setting the environment variableKALEIDO_PATH=/path/installed/kaleido/ will ensure that applications that were built with thekaleido feature enabled can locate thekaleido executable and use it to generate static images.

Kaleido binaries are available on Githubrelease page. It currently supports Linux(x86_64), Windows(x86_64) and MacOS(x86_64/aarch64).

Plotly.rs can be used with a WASM-based frontend framework. Note that thekaleido andplotly_static static export features are not supported in WASM environments and will throw a compilation error if used.

The needed dependencies are automatically enabled forwasm32 targets at compile time and there is no longer a need for the customwasm flag in this crate.

First, make sure that you have the Plotly JavaScript library in your base HTML template:

<!-- index.html --><!doctype html><htmllang="en"><head><!-- snip --><scriptsrc="https://cdn.plot.ly/plotly-2.14.0.min.js"></script></head><!-- snip --></html>

A simplePlot component would look as follows, usingYew as an example frontend framework:

use plotly::{Plot,Scatter};use yew::prelude::*;#[function_component(PlotComponent)]pubfnplot_component() ->Html{let p = yew_hooks::use_async::<_,_,()>({let id ="plot-div";letmut plot =Plot::new();let trace =Scatter::new(vec![0,1,2],vec![2,1,0]);        plot.add_trace(trace);asyncmove{            plotly::bindings::new_plot(id,&plot).await;Ok(())}});use_effect_with((),move |_|{        p.run();        ||()});html!{        <div id="plot-div"></div>}}

In situations where the number of points of a timeseries is extremely large, generating a plot and visualizing it using plotly will be slow or not possible.

For such cases, it is ideal to use a downsampling method that preserves the visual characteristics of the timeseries. One such method is to use the Largest Triangle Three Bucket (LTTB) method. The MinMaxLTTB or classical LTTB method can be used to downsample the timeseries prior to generating the static HTML plots. An example of how this can be achieved can be found inexamples/downsampling directory using theminmaxlttb-rs crate.

The following feature flags are available:

Since version0.13.0 support for exporting to static images is based on using a new crate calledplotly_static that uses WebDriver and browser automation for static export functionality.

This feature flag automatically enables the usage of theplotly_static dependency as well as thechromedriver andwebdriver_download features of that crate. For more details about these feature flags, refer to theplotly_staticdocumentation.

The other related features allow controlling other aspects of theplotly_static crate

• static_export_chromedriver
• static_export_geckodriver
• static_export_wd_download

Adds trait implementations so thatimage::RgbImage andimage::RgbaImage can be used more directly with theplotly::Image trace.

Adds support for creating plots directly usingndarray types.

By default, the CDN version ofplotly.js is used in the library and in the generated HTML files. This feature can be used to opt in for embeddingplotly.min.js in the generated HTML files. The benefit is that the plot will load faster in the browser.

However, there are two downsides of using this feature flag, one is that the resulting html will be much larger, as a copy of theplotly.min.js library is embedded in each HTML file. The second, more relevant, is that a copy of theplotly.min.js library needs to be compiled in theplotly-rs library itself which increases the size by approx3.5 Mb.

When the feature is enabled, users can still opt in for the CDN version by using the methoduse_cdn_js.

Note that when usingPlot::to_inline_html(), it is assumed that theplotly.js library is already in scope within the HTML file, so enabling this feature flag will have no effect.

Adds plot save functionality to the following formats:png,jpeg,webp,svg,pdf andeps.

RequiresKaleido to have been previously installed on the host machine. See the following feature flag andKaleido external dependency.

Enable download and install of Kaleido binary at build time fromKaleido releases on the host machine.SeeKaleido external dependency for more details.

• If you've spotted a bug or would like to see a new feature, please submit an issue on theissue tracker.

• Pull requests are welcome, see thecontributing guide for more information.

See theCode of Conduct for more information.

Plotly.rs is distributed under the terms of the MIT license, seeLICENSE.