Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/yuankunzhang/charming

A visualization library for Rust
https://github.com/yuankunzhang/charming

chart data-science rust visualization webassembly

Last synced: 26 days ago
JSON representation

A visualization library for Rust

Host: GitHub
URL: https://github.com/yuankunzhang/charming
Owner: yuankunzhang
License: apache-2.0
Created: 2023-06-29T15:28:29.000Z (over 1 year ago)
Default Branch: main
Last Pushed: 2024-08-10T22:32:16.000Z (3 months ago)
Last Synced: 2024-10-02T01:01:14.963Z (about 1 month ago)
Topics: chart, data-science, rust, visualization, webassembly
Language: Rust
Homepage:
Size: 1.52 MB
Stars: 1,737
Watchers: 8
Forks: 63
Open Issues: 32
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE

Awesome Lists containing this project

awesome-rust-list - Charming
awesome-rust-list - Charming

README

        # Charming - A Rust Visualization Library

[![crates.io](https://img.shields.io/crates/v/charming.svg)](https://crates.io/crates/charming)

[![docs.rs](https://docs.rs/charming/badge.svg)](https://docs.rs/charming)

[![discord](https://dcbadge.vercel.app/api/server/u3wmVPcW?style=flat)](https://discord.gg/u3wmVPcW)

Charming is a powerful and versatile chart rendering library for Rust that leverages the power of [Apache ECharts](https://echarts.apache.org/en/index.html) 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

        Dark

        Vintage

    

    

        Westeros

        Essos

        Wonderland

    

    

        Walden

        Chalk

        Infographic

    

    

        Macarons

        Roma

        Shine

    

    

        Purple Passion

        Halloween

    

Future versions of Charming will support custom themes.

## Basic Usage

Add charming as a dependency:

```sh

$ cargo add charming

```

Refer to the documentation of the [`Chart`](https://docs.rs/charming/latest/charming/struct.Chart.html) 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](https://github.com/denoland/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:

```rust

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:

![](img/nightingale.svg)

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

![](img/encode-and-matrix.svg)

### 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

```rs

// 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:

```rust

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





















### Boxplot Charts









### Candlestick Charts









### Funnel Charts









### Gauge Charts











### Graph Charts









### Heatmap Charts







### Line Charts





































### Parallel Charts









### Pie Charts











### Radar Charts











### Sankey Charts











### Scatter Charts















### Sunburst Charts







### Theme River Charts







### Tree Charts