# 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