/charming

A visualization library for Rust

Primary LanguageRustApache License 2.0Apache-2.0

Charming - A Rust Visualization Library

crates.io docs.rs

Charming is a powerful and versatile chart rendering library for Rust that leverages the power of Apache ECharts to deliver high-quality data visualizations. Built with the Rust programming language, this library aims to provide the Rust ecosystem with an intuitive and effective way to generate and visualize charts, using a declarative and user-friendly API.

Highlights:

  • Easy-to-use, declaritive API.
  • Abundant chart types with rich and customizable chart themes and styles.
  • Ready to use in WebAssembly environments.
  • Rendering to multiple formats, including HTML, SVG, PNG, JPEG, GIF, WEBP, PNM, TIFF, TGA, DDS, BMP, ICO, HDR, OPENEXR, FARBFELD, AVIF, and QOI.

Themes

Default

Default

Dark

Dark

Vintage

Vintage

Westeros

Vintage

Essos

Essos

Wonderland

Essos

Walden

Walden

Chalk

Chalk

Infographic

Infographic

Macarons

Macarons

Roma

Roma

Shine

Shine

Purple Passion

Purple Passion

Halloween

Halloween

Future versions of Charming will support custom themes.

Basic Usage

Add charming as a dependency:

$ cargo add charming

Refer to the documentation of the Chart struct for how to create a chart with various components.

Once you create a chart, you can render it into various format. Charming provides three types of renderers:

  • HTML renderer: HtmlRenderer renders a chart into an HTML fragments and offloads the actual rendering to user's web browser for an interactive, seamless experience. This renderer is useful when you want to render a chart on the client side, e.g., in a web application.
  • Image renderer: ImageRenderer renders a chart into an image file. This renderer makes use of an embed deno_core engine to execute the JavaScript code of Echarts and generate an image file. This renderer is disabled by default, and you need to enable the ssr (Server-Side Rendering) feature to use it.
  • WASM renderer: WasmRenderer renders a chart in a WebAssembly runtime. This renderer is disabled by default, and you need to enable the wasm feature to use it. Note that the wasm feature and ssr feature are mutually exclusive.

Here is an example of drawing a simple pie chart into an SVG file:

use charming::{
    component::Legend,
    element::ItemStyle,
    series::{Pie, PieRoseType},
    Chart, ImageRenderer
};

fn main() {
    let chart = Chart::new()
        .legend(Legend::new().top("bottom"))
        .series(
            Pie::new()
                .name("Nightingale Chart")
                .rose_type(PieRoseType::Radius)
                .radius(vec!["50", "250"])
                .center(vec!["50%", "50%"])
                .item_style(ItemStyle::new().border_radius(8))
                .data(vec![
                    (40.0, "rose 1"),
                    (38.0, "rose 2"),
                    (32.0, "rose 3"),
                    (30.0, "rose 4"),
                    (28.0, "rose 5"),
                    (26.0, "rose 6"),
                    (22.0, "rose 7"),
                    (18.0, "rose 8"),
                ]),
        );

    let mut renderer = ImageRenderer::new(1000, 800);
    renderer.save(&chart, "/tmp/nightingale.svg");
}

This code creates the following SVG file:

As another example, the code file gallery/src/dataset/encode_and_matrix.rs draws a complex chart with four sub-charts:

Crate Feature Flags

The following two feature flags are available, note that they can't be used together:

  • ssr - Enables the ImageRenderer, which provides the capability to generate image files.
  • wasm - Enables the WasmRenderer, which provides the capability to render charts in WebAssembly runtime.

Renderers

// Use HtmlRenderer.
use charming::HtmlRenderer;

// Chart dimension 1000x800.
let renderer = HtmlRenderer::new("my charts", 1000, 800);
// Render the chart as HTML string.
let html_str = renderer.render(&chart).unwrap();
// Save the chart as HTML file.
renderer.save(&chart, "/tmp/chart.html").unwrap();


// Use ImageRenderer. The `ssr` feature needs to be enabled.
use charming::{ImageRenderer, ImageFormat};

// Chart dimension 1000x800.
let mut renderer = ImageRenderer::new(1000, 800);
// Render the chart as SVG string.
renderer.render(&chart).unwrap();
// Render the chart as PNG bytes.
renderer.render_format(ImageFormat::PNG, &chart).unwrap();
// Save the chart as SVG file.
renderer.save(&chart, "/tmp/chart.svg").unwrap();
// Save the chart as PNG file.
renderer.save_format(ImageFormat::PNG, &chart, "/tmp/chart.png");


// Use WasmRenderer. The `wasm` feature needs to be enabled.
use charming::WasmRenderer;

// Chart dimension 1000x800.
let renderer = WasmRenderer::new(1000, 800);
// Render the chart in the WebAssembly runtime
renderer.render(&chart).unwrap();

Themes

Charming supports a number of themes out of the box. You can use the Theme enum to specify a theme for your chart. For instance, the following code snippet shows how to use the Westeros theme:

use charming::{Chart, ImageRenderer};
use charming::theme::Theme;
use charming::component::Title;

ImageRenderer::new(1000, 800).theme(Theme::Westeros).save(
    &Chart::new().title(Title::new().text("Westeros")),
    "/tmp/westeros.svg",
);

Future versions of Charming will support custom themes.

Gallery

Here are some selected chart examples. Click on any single chart to view its source code file.

You can also clone the repo and run cargo run --bin gallery to view the interactive charts on the rendered HTML page.

Bar Charts

Bar with Background Basic Bar Radial Polar Bar Label Position Set Style of Single Bar Stacked Column Tangential Polar Bar Waterfall World Population

Boxplot Charts

Boxplot Light Velocity Multiple Categories

Candlestick Charts

Basic Candlestick Shanghai Index

Funnel Charts

Funnel Chart Multiple Funnels

Gauge Charts

Gauge Barometer Gauge Basic Gauge Simple

Graph Charts

Hide Overlapped Label Les Miserables

Heatmap Charts

Heatmap on Cartesian

Line Charts

Area Pieces Basic Area Basic Line Confidence Band Data Transform Filter Distribution of Electricity Gradient Stacked Area Large Scale Area Line Gradient Rainfall Rainfall Vs. Evaporation Smoothed Line Stacked Area Stacked Line Temperature Change Two Value-Axes in Polar

Parallel Charts

Basic Parallel Parallel AQI

Pie Charts

Nightingale Nightingale Referer of a Website

Radar Charts

Basic Radar Multiple Radar Proportion of Browsers

Sankey Charts

Basic Sankey Node Align Left Sankey Sankey Orient Vertical

Scatter Charts

Anscombe Quartet Basic Scatter Bubble Chart Effect Scatter Punch Card of Github

Sunburst Charts

Drink Flavors

Theme River Charts

Theme River LastFM

Tree Charts

From Left to Right Tree Multiple Trees