Crate plotly_static

Plotly Static Image Export

A Rust library for exporting Plotly plots to static images using headless browsers via WebDriver.

This library provides a interface for converting Plotly plots provided as JSON values into various static image formats (PNG, JPEG, WEBP, SVG, PDF) using WebDriver and headless browsers.

Features

• Multiple Formats: Support for PNG, JPEG, WEBP, SVG, and PDF export
• Headless Rendering: Uses headless browsers for rendering
• WebDriver Support: Supports both Chrome (chromedriver) and Firefox (geckodriver)
• Configurable: Customizable dimensions, scale, and browser capabilities
• Offline Mode: Can work with offline bundled JavaScript libraries
• Automatic Management: Handles WebDriver process lifecycle and cleanup
• Parallelism: Designed for use in parallel environments (tests, etc.)
• Logging Support: Integrated logging with env_logger support

Quick Start

// This example requires a WebDriver-compatible browser (Chrome/Firefox).
// It cannot be run as a doc test.
use plotly_static::{StaticExporterBuilder, ImageFormat};
use serde_json::json;
use std::path::Path;

// Create a simple plot
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");

Features and Dependencies

Required Features

You must enable one of the following features:

• chromedriver: Use Chrome/Chromium for rendering
• geckodriver: Use Firefox for rendering

Optional Features

• webdriver_download: Automatically download WebDriver binaries at build time

Example Cargo.toml

[dependencies]
plotly_static = { version = "0.0.3", features = ["chromedriver", "webdriver_download"] }

Advanced Usage

Custom Configuration

use plotly_static::StaticExporterBuilder;

let exporter = StaticExporterBuilder::default()
    .webdriver_port(4444)
    .webdriver_url("http://localhost")
    .spawn_webdriver(true)
    .offline_mode(true)
    .webdriver_browser_caps(vec![
        "--headless".to_string(),
        "--no-sandbox".to_string(),
        "--disable-gpu".to_string(),
    ])
    .build()
    .expect("Failed to build StaticExporter");

Browser Binary Configuration

You can specify custom browser binaries using environment variables:

# For Chrome/Chromium
export BROWSER_PATH="/path/to/chrome"

# For Firefox
export BROWSER_PATH="/path/to/firefox"

The library will automatically use these binaries when creating WebDriver sessions.

String Export

// This example requires a running WebDriver (chromedriver/geckodriver) and a browser.
// It cannot be run as a doc test.
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 build StaticExporter");

let svg_data = exporter.write_to_string(
    &plot,
    ImageFormat::SVG,
    800,
    600,
    1.0
).expect("Failed to export plot");

// svg_data contains SVG markup that can be embedded in HTML

Logging Support

The library supports logging via the log crate. Enable it with env_logger:

use plotly_static::StaticExporterBuilder;

// Initialize logging (typically done once at the start of your application)
env_logger::init();

// Set log level via environment variable
// RUST_LOG=debug cargo run

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

Parallel Usage

The library is designed to work safely in parallel environments:

use plotly_static::{StaticExporterBuilder, ImageFormat};
use std::sync::atomic::{AtomicU32, Ordering};

// Generate unique ports for parallel usage
static PORT_COUNTER: AtomicU32 = AtomicU32::new(4444);

fn get_unique_port() -> u32 {
    PORT_COUNTER.fetch_add(1, Ordering::SeqCst)
}

// Each thread/process should use a unique port
let mut exporter = StaticExporterBuilder::default()
    .webdriver_port(get_unique_port())
    .build()
    .expect("Failed to build StaticExporter");

WebDriver Management

The library automatically manages WebDriver processes:

• Automatic Detection: Detects if WebDriver is already running on the specified port
• Process Spawning: Automatically spawns WebDriver if not already running
• Connection Reuse: Reuses existing WebDriver sessions when possible
• Cleanup: Automatically terminates WebDriver processes when StaticExporter is dropped
• External Sessions: Can connect to externally managed WebDriver sessions

WebDriver Configuration

Set the WEBDRIVER_PATH environment variable to specify a custom WebDriver binary location (should point to the full executable path):

export WEBDRIVER_PATH=/path/to/chromedriver
cargo run

Or use the webdriver_download feature for automatic download at build time.

Error Handling

The library uses anyhow::Result for error handling. Common errors include:

• WebDriver not available or not running
• Invalid Plotly JSON format
• File system errors
• Browser rendering errors

Browser Support

• Chrome/Chromium: Full support via chromedriver
• Firefox: Full support via geckodriver
• Safari: Not currently supported
• Edge: Not currently supported

Performance Considerations

• Reuse Exporters: Reuse StaticExporter instances for multiple exports
• Parallel Usage: Use unique ports for parallel operations
• WebDriver Reuse: The library automatically reuses WebDriver sessions when possible
• Resource Cleanup: WebDriver processes are automatically cleaned up on drop

Comparison with Kaleido

• No custom Chromium/Chrome external dependency: Uses standard WebDriver instead of proprietary Kaleido
• Better Browser Support: Works with any WebDriver-compatible browser: Chrome/Chromium,Firefox,Brave
• Extensible: Easy to control browser capabilities and customize the StaticExporter instance

Limitations

• Requires a WebDriver-compatible browser
• PDF export uses browser JavaScript html2pdf (not native Plotly PDF)
• EPS is no longer supported and will be removed
• Slightly slower than Kaleido

License

MIT License - see LICENSE file for details.

Structs

StaticExporter

Main struct for exporting Plotly plots to static images.

StaticExporterBuilder

Builder for configuring and creating a StaticExporter instance.

Enums

ImageFormat

Supported image formats for static image export.