plotly_static

Export Plotly plots to static images using WebDriver and headless browsers.

Overview

plotly_static provides a Rust interface for converting Plotly plots from JSON data into various static image formats (PNG, JPEG, WEBP, SVG, PDF) using WebDriver and headless browsers.

Features

Async/Sync API Support: Support for both async and sync contexts
Multiple Formats: PNG, JPEG, WEBP, SVG, PDF
Browser Support: Chrome/Chromium (chromedriver) and Firefox (geckodriver)
Efficient: Reuse StaticExporter instances for multiple exports
String Export: Base64 and SVG output for web applications
Parallel Safe: Designed for concurrent usage
Automatic Management: Handles WebDriver lifecycle and cleanup

Quick Start

use plotly_static::{StaticExporterBuilder, ImageFormat};
use serde_json::json;
use std::path::Path;

// Create a simple plot as JSON
let plot = json!({
    "data": [{
        "type": "scatter",
        "x": [1, 2, 3, 4],
        "y": [10, 11, 12, 13]
    }],
    "layout": {
        "title": "Simple Scatter Plot"
    }
});

// Build and use StaticExporter
let mut exporter = StaticExporterBuilder::default()
    .build()
    .expect("Failed to build StaticExporter");

// Export to PNG
exporter.write_fig(
    Path::new("my_plot"),
    &plot,
    ImageFormat::PNG,
    800,
    600,
    1.0
).expect("Failed to export plot");

Usage

Add to your Cargo.toml:

[dependencies]
plotly_static = { version = "0.1", features = ["chromedriver", "webdriver_download"] }
serde_json = "1.0"

Feature Flags

chromedriver: Use Chromedriver and Chrome/Chromium browser for rendering and export
geckodriver: Use Geckodriver Firefox browser for rendering for rendering and export
webdriver_download: Auto-download the chosen WebDriver binary

Prerequisites

Browser: Chrome/Chromium or Firefox installed
WebDriver: Manually installed or automatically downloaded and installed with the webdriver_download feature
Internet Connectivity: Required for WebDriver download when using the auto-download and install feature

Async Support

The library supports async operations. To use the async API you need to call build_async instead of build on the StaticExporterBuilder . This will return an AsyncStaticExporter instance where the write_fig and write_to_string methods are async.

use plotly_static::StaticExporterBuilder;

let exporter = StaticExporterBuilder::default()
    .build_async()
    .expect("Failed to build AsyncStaticExporter");

Never use the sync API in async contexts. The sync API wraps the async API and uses a tokio::runtime::Runtime instance internally. Using the sync API in an async context will cause runtime errors such as e.g., "Cannot drop a runtime in a context where blocking is not allowed. This happens when a runtime is dropped from within an asynchronous context." or similar ones.

Advanced Usage

Static Exporter Reuse

use plotly_static::{StaticExporterBuilder, ImageFormat};
use serde_json::json;
use std::path::Path;

let plot1 = json!({
    "data": [{"type": "scatter", "x": [1,2,3], "y": [4,5,6]}],
    "layout": {"title": "Plot 1"}
});

let plot2 = json!({
    "data": [{"type": "scatter", "x": [2,3,4], "y": [5,6,7]}],
    "layout": {"title": "Plot 2"}
});

let mut exporter = StaticExporterBuilder::default()
    .build()
    .expect("Failed to create StaticExporter");

// Reuse for multiple exports
exporter.write_fig(Path::new("plot1"), &plot1, ImageFormat::PNG, 800, 600, 1.0)?;
exporter.write_fig(Path::new("plot2"), &plot2, ImageFormat::JPEG, 800, 600, 1.0)?;

String Export

use plotly_static::{StaticExporterBuilder, ImageFormat};
use serde_json::json;

let plot = json!({
    "data": [{"type": "scatter", "x": [1,2,3], "y": [4,5,6]}],
    "layout": {}
});

let mut exporter = StaticExporterBuilder::default()
    .build()
    .expect("Failed to create StaticExporter");

// Get base64 data for web embedding
let base64_data = exporter.write_to_string(&plot, ImageFormat::PNG, 400, 300, 1.0)?;

// Get SVG data (vector format)
let svg_data = exporter.write_to_string(&plot, ImageFormat::SVG, 400, 300, 1.0)?;

Custom Configuration

use plotly_static::StaticExporterBuilder;

let mut exporter = StaticExporterBuilder::default()
    .webdriver_port(4445)  // Unique port for parallel usage
    .offline_mode(true)    // Use bundled JavaScript
    .webdriver_browser_caps(vec![
        "--headless".to_string(),
        "--no-sandbox".to_string(),
    ])
    .build()?;

Environment Variables

WEBDRIVER_PATH: Custom WebDriver binary location
BROWSER_PATH: Custom browser binary location

Examples

Check the self contatined examples in the examples folder.

Similar examples are available in the Plotly.rs package, in Plotly.rs Book as well as the example in Plotly.rs examples/static_export.

Documentation

License

This package is licensed under the MIT License.

plotly_static 0.1.0