Introduction

What is Charton? (The Core Idea)

Charton is a modern Rust visualization library designed around a simple, declarative framework for data visualization.

  • Declarative API: It offers an API similar to Python's Altair/Vega-Lite, allowing users to define "what to visualize" rather than "how to draw it.". That is, "the Grammar of Graphics".
  • Native Polars Support: Charton is tightly integrated with the high-performance Rust DataFrame library Polars, enabling efficient, zero-copy data plotting.
  • Dual Rendering Capability: You can utilize its pure Rust SVG renderer for dependency-free plotting, or leverage its IPC mechanism to seamlessly connect with external Python visualization ecosystems like Altair and Matplotlib.

Design Philosophy and Key Advantages

Charton is engineered to be an efficient, safe, and flexible solution, built on the principle that visualization should be declarative.

  • 🚀 Performance and Safety: It leverages Rust's strong type system to achieve compile-time safety and utilizes Polars' integration for superior data handling performance.
  • 💡 Layered and Expressive: It features a multi-layer plotting architecture that easily combines various marks (e.g., points, lines, bars, boxplots, error bars) within a shared coordinate system to create complex composite visualizations.
  • 🌐 Frontend Ready: It can generate standard Vega-Lite JSON specifications, making it ready for easy integration into modern web applications using libraries like React-Vega or Vega-Embed.
  • 🔗 Efficient Integration: Through Inter-Process Communication (IPC), it efficiently communicates with external Python libraries, avoiding slow, temporary file operations and maintaining compatibility with environments like Conda in Jupyter.
  • 📓 Jupyter Interactivity: It offers native support for the evcxr Jupyter Notebook environment, enabling interactive and real-time exploratory data analysis.

System Architecture

Charton adopts a modern, decoupled architecture designed for high-performance data processing and cross-language interoperability.

┌───────────────────────────────────────────────────────────────────────────┐
│                            Input Layer                                    │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────────────────┐ │
│  │ Rust Polars  │    │ External     │    │ Jupyter/evcxr Interactive    │ │
│  │ DataFrame/   │    │ Datasets     │    │ Input                        │ │
│  │ LazyFrame    │    │ (CSV/Parquet)│    │ (Notebook cell data/commands)│ │
│  └──────────────┘    └──────────────┘    └──────────────────────────────┘ │
└────────────────────────────────────┬──────────────────────────────────────┘
                                     │
┌────────────────────────────────────▼──────────────────────────────────────┐
│                          Core Layer                                       │
│  ┌──────────────────────────────────────────────────────────────────────┐ │
│  │            Charton Core Engine                                       │ │
│  │  ┌──────────────┐    ┌───────────────┐    ┌──────────────────────┐   │ │
│  │  │ Declarative  │    │ Layered       │    │ Cross-backend Data   │   │ │
│  │  │ API (Altair- │    │ Chart         │    │ Converter            │   │ │
│  │  │ style)       │    │ Management    │    │ (Rust ↔ Python/JSON) │   │ │
│  │  └──────────────┘    │ (LayeredChart)│    └──────────────────────┘   │ │
│  │                      └───────────────┘                               │ │
│  │  ┌──────────────┐    ┌───────────────┐    ┌──────────────────────┐   │ │
│  │  │ Data         │    │ IPC           │    │ Vega-Lite Spec       │   │ │
│  │  │ Validation/  │    │ Communication │    │ Generator            │   │ │
│  │  │ Mapping      │    │ Module        │    │                      │   │ │
│  │  └──────────────┘    └───────────────┘    └──────────────────────┘   │ │
│  └──────────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────┬──────────────────────────────────────┘
                                     │
┌────────────────────────────────────▼──────────────────────────────────────┐
│                        Render Backends                                    │
│  ┌──────────────────────┐    ┌────────────────────────────────────────┐   │
│  │ Rust Native Backend  │    │ External Cross-Language Backends       │   │
│  │                      │    │                                        │   │
│  │  ┌────────────────┐  │    │  ┌─────────────┐  ┌──────────────────┐ │   │
│  │  │ Pure Rust SVG  │  │    │  │ Altair      │  │ Matplotlib       │ │   │
│  │  │ Renderer       │  │    │  │ Backend     │  │ Backend          │ │   │
│  │  └────────────────┘  │    │  │ (Python IPC)│  │ (Python IPC)     │ │   │
│  │                      │    │  └─────────────┘  └──────────────────┘ │   │
│  │  ┌────────────────┐  │    │                                        │   │
│  │  │ Wasm Renderer  │  │    │  ┌────────────┐  ┌──────────────────┐  │   │
│  │  │ (Partial       │  │    │  │ Other      │  │ Extended Backends│  │   │
│  │  │  Support)      │  │    │  │ Python     │  │ (Future)         │  │   │
│  │  └────────────────┘  │    │  │ Viz Libs   │  │ (R/Julia, etc.)  │  │   │
│  │                      │    │  └────────────┘  └──────────────────┘  │   │
│  └──────────────────────┘    └────────────────────────────────────────┘   │
└────────────────────────────────────┬──────────────────────────────────────┘
                                     │
┌────────────────────────────────────▼──────────────────────────────────────┐
│                          Output Layer                                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐   │
│  │ SVG Vector   │  │ Vega-Lite    │  │ PNG Bitmap   │  │ Jupyter      │   │
│  │ Graphics     │  │ JSON         │  │ Image        │  │ Inline       │   │
│  │ (Native/Wasm)│  │ (for Web)    │  │ (via Ext.)   │  │ Rendering    │   │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘   │
└───────────────────────────────────────────────────────────────────────────┘

1. Input Layer (Data Orchestration)

  • Polars-Native: Unlike other libraries that require heavy data cloning, Charton is built on Apache Arrow (via Polars), enabling efficient, zero-copy data access.
  • Versatile Sourcing: It supports DataFrame and LazyFrame, allowing for out-of-core data processing before visualization.

2. Core Layer (The Grammar Engine)

  • Declarative DSL: A type-safe implementation of the Grammar of Graphics, allowing users to compose complex visualizations using intuitive tuples (e.g., .encode((x, y, color))).
  • Universal Data Bridge: This is the core innovation of Charton. It utilizes Parquet-serialized bytes as an intermediate format to exchange data between different Polars versions and languages, effectively bypassing Rust's orphan rules and dependency conflicts.
  • Vega-Lite Spec Generator: A high-level compiler that transforms Rust structures into standard Vega-Lite JSON for seamless frontend integration.

3. Render Backends (Multi-Engine)

  • Rust Native Backend: A zero-dependency, pure Rust implementation. It uses a custom SVG renderer for ultra-fast, server-side batch generation and provides partial support for WebAssembly (Wasm).
  • IPC Bridge (External): For features not yet in the native engine, Charton provides a high-speed Inter-Process Communication (IPC) bridge to Python’s mature ecosystem (Altair/Matplotlib), eliminating the need for slow temporary disk I/O.

4. Output Layer (Multi-Format Delivery)

  • Vector & Raster: Support for SVG and high-resolution PNG (via resvg).
  • Web & Notebook: Direct JSON output for React/Vue integration and inline rendering for evcxr Jupyter notebooks.

Why This Architecture Matters

🚀 Solving the "Version Hell"

In the Rust ecosystem, if your project depends on Polars v0.50 and a plotting library depends on v0.40, your code won't compile. Charton’s Parquet-encoded IPC bypasses this entirely, making it the most robust visualization tool for production Rust environments.

🔌 Hot-Swappable Backends

You can develop interactively using the Altair backend to leverage its rich feature set, and then switch to the Native SVG backend for deployment to achieve maximum performance and minimum container size.

🌐 Frontend-First Design

By generating standard Vega-Lite JSON, Charton allows you to handle heavy data lifting in Rust while letting the browser’s GPU handle the final rendering via Vega-Embed or React-Vega.