Rust可视化工具库plotly_kaleido的使用指南

介绍

plotly_kaleido是一个Rust库，它为Plotly图表提供了静态导出和高质量渲染功能。这个库实际上是Plotly Kaleido库的Rust绑定，Kaleido是一个无头浏览器，专门用于将Plotly图表导出为各种静态格式。

主要特点：

• 支持导出为PNG、JPEG、WebP、SVG、PDF和EPS格式
• 提供高质量的渲染输出
• 不需要外部浏览器或显示服务器
• 跨平台支持

安装

在Cargo.toml中添加依赖：

[dependencies]
plotly = "0.8"
plotly_kaleido = "0.8"

基本使用方法

1. 导出图表到文件

use plotly::{Plot, Scatter};
use plotly_kaleido::Kaleido;

fn main() {
    // 创建一个简单的折线图
    let trace = Scatter::new(vec![1, 2, 3], vec![4, 5, 6]);
    let mut plot = Plot::new();
    plot.add_trace(trace);
    
    // 初始化Kaleido
    let kaleido = Kaleido::new().expect("Failed to initialize Kaleido");
    
    // 保存为PNG
    kaleido
        .save(&plot, "output.png", 800, 600)
        .expect("Failed to save plot");
    
    // 保存为SVG
    kaleido
        .save(&plot, "output.svg", 800, 600)
        .expect("Failed to save plot");
}

2. 获取图表二进制数据

use plotly::{Plot, Scatter};
use plotly_kaleido::Kaleido;

fn main() {
    let trace = Scatter::new(vec![1, 2, 3], vec![4, 5, 6]);
    let mut plot = Plot::new();
    plot.add_trace(trace);
    
    let kaleido = Kaleido::new().unwrap();
    
    // 获取PNG格式的二进制数据
    let png_data = kaleido.to_image(&plot, "png", 800, 600).unwrap();
    
    // 获取SVG格式的字符串
    let svg_data = kaleido.to_image(&plot, "svg", 800, 600).unwrap();
}

高级用法

1. 自定义导出选项

use plotly::{Plot, Scatter};
use plotly_kaleido::{Kaleido, KaleidoOptions};

fn main() {
    let trace = Scutter::new(vec![1, 2, 3], vec![4, 5, 6]);
    let mut plot = Plot::new();
    plot.add_trace(trace);
    
    // 自定义Kaleido选项
    let options = KaleidoOptions::new()
        .scale(2.0)  // 缩放因子
        .format("png")  // 默认格式
        .width(1024)  // 默认宽度
        .height(768);  // 默认高度
    
    let kaleido = Kaleido::with_options(options).unwrap();
    
    kaleido.save(&plot, "high_res.png", 1024, 768).unwrap();
}

2. 批量导出图表

use plotly::{Plot, Scatter};
use plotly_kaleido::Kaleido;

fn main() {
    let kaleido = Kaleido::new().unwrap();
    
    // 创建多个图表
    let plots = vec![
        create_plot("Plot 1", vec![1, 2, 3], vec![4, 5, 6]),
        create_plot("Plot 2", vec![1, 2, 3], vec![6, 5, 4]),
    ];
    
    // 批量导出
    for (i, plot) in plots.iter().enumerate() {
        let filename = format!("plot_{}.png", i + 1);
        kaleido.save(plot, &filename, 800, 600).unwrap();
    }
}

fn create_plot(title: &str, x: Vec<i32>, y: Vec<i32>) -> Plot {
    let trace = Scatter::new(x, y).name(title);
    let mut plot = Plot::new();
    plot.add_trace(trace);
    plot
}

完整示例demo

下面是一个完整的示例，展示如何创建多个图表并使用plotly_kaleido导出：

use plotly::{common::Mode, Plot, Scatter};
use plotly_kaleido::{Kaleido, KaleidoOptions};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建Kaleido实例，带有自定义选项
    let kaleido = Kaleido::with_options(
        KaleidoOptions::new()
            .scale(1.5)
            .format("png")
            .width(1200)
            .height(800),
    )?;

    // 创建多个不同类型的图表
    let plots = vec![
        create_line_plot("线性图", vec![1, 2, 3], vec![4, 5, 6]),
        create_scatter_plot("散点图", vec![1, 2, 3], vec![6, 5, 4]),
    ];

    // 批量导出图表
    for (i, plot) in plots.iter().enumerate() {
        let filename = format!("chart_{}.png", i + 1);
        kaleido.save(plot, &filename, 1200, 800)?;
        println!("已导出: {}", filename);
    }

    Ok(())
}

// 创建折线图
fn create_line_plot(title: &str, x: Vec<i32>, y: Vec<i32>) -> Plot {
    let trace = Scatter::new(x, y)
        .name(title)
        .mode(Mode::LinesMarkers);  // 线+标记点模式
    let mut plot = Plot::new();
    plot.add_trace(trace);
    plot.set_layout(plotly::Layout::new().title(plotly::common::Title::new(title)));
    plot
}

// 创建散点图
fn create_scatter_plot(title: &str, x: Vec<i32>, y: Vec<i32>) -> Plot {
    let trace = Scatter::new(x, y)
        .name(title)
        .mode(Mode::Markers);  // 仅标记点模式
    let mut plot = Plot::new();
    plot.add_trace(trace);
    plot.set_layout(
        plotly::Layout::new()
            .title(plotly::common::Title::new(title))
            .x_axis(plotly::layout::Axis::new().title("X轴"))
            .y_axis(plotly::layout::Axis::new().title("Y轴")),
    );
    plot
}

注意事项

1. 性能考虑：Kaleido的初始化可能比较耗时，建议在应用程序中重用Kaleido实例而不是频繁创建和销毁。

2. 错误处理：Kaleido可能因为各种原因失败（如缺少依赖库），请确保正确处理错误。

3. 格式支持：确保使用支持的格式（png, jpeg, webp, svg, pdf, eps）。

4. 资源清理：Kaleido会启动一个子进程，当Kaleido实例被drop时，子进程会被终止。

5. 跨平台：Kaleido支持Windows、macOS和Linux，但可能需要安装额外的系统依赖。

通过plotly_kaleido，你可以轻松地将Plotly图表导出为高质量的静态图像，非常适合生成报告、文档或网页中的图表。