Crate embedded_charts

Expand description

§Embedded Charts

A production-ready, no_std graph framework for embedded systems using embedded-graphics.

This library provides comprehensive chart types (line, bar, pie, scatter, gauge), axes, grids, legends, real-time data streaming capabilities, and customizable styling while maintaining memory efficiency and performance suitable for resource-constrained environments.

§Features

Memory Efficient: Static allocation with compile-time bounds, no heap usage
Performance Optimized: Designed for real-time rendering on embedded systems
Flexible: Plugin-like architecture for custom chart types
Easy to Use: Fluent builder API with sensible defaults
std/no_std Compatible: Full compatibility with both desktop and embedded environments
Rich Chart Types: Line, bar, pie, gauge, and scatter charts with professional styling
Real-time Animation: Streaming data with smooth transitions and configurable easing
Professional Styling: Built-in themes, color palettes, and typography support

§Chart Types

§Line Charts

Multi-series line charts with markers, area filling, and smooth curves:

use embedded_charts::prelude::*;
use embedded_graphics::pixelcolor::Rgb565;

let chart = LineChart::builder()
    .line_color(Rgb565::BLUE)
    .line_width(2)
    .with_markers(MarkerStyle {
        shape: MarkerShape::Circle,
        size: 6,
        color: Rgb565::RED,
        visible: true,
    })
    .build()?;

§Bar Charts

Vertical and horizontal bar charts with stacking support:

use embedded_charts::prelude::*;
use embedded_graphics::pixelcolor::Rgb565;

let chart = BarChart::builder()
    .orientation(BarOrientation::Vertical)
    .bar_width(BarWidth::Fixed(20))
    .colors(&[Rgb565::GREEN])
    .build()?;
Ok(())

§Pie Charts

Full circle pie charts with professional styling:

use embedded_charts::prelude::*;
use embedded_graphics::pixelcolor::Rgb565;

let chart = PieChart::builder()
    .radius(80)
    .colors(&[Rgb565::BLUE, Rgb565::RED, Rgb565::GREEN])
    .with_title("Market Share")
    .build()?;
Ok(())

§Donut Charts

Pie charts with hollow centers for improved information density:

use embedded_charts::prelude::*;
use embedded_graphics::pixelcolor::Rgb565;

// Balanced donut chart (50% inner radius)
let chart = PieChart::builder()
    .radius(80)
    .donut(40) // Inner radius of 40 pixels
    .colors(&[Rgb565::BLUE, Rgb565::RED, Rgb565::GREEN])
    .with_title("Storage Usage")
    .build()?;
Ok(())

§Donut Chart Best Practices for Embedded Systems

Optimal Inner Radius Ratios:

Thin donut (20-30% inner): Emphasizes data segments, good for detailed analysis
Balanced donut (40-60% inner): Best overall readability and visual balance
Thick donut (70-80% inner): Maximizes center space for additional content

Memory Considerations:

Donut charts use the same memory footprint as regular pie charts
Center area can display totals, units, or status without additional memory cost
Smaller outer radius improves performance on resource-constrained systems

Display Size Guidelines:

Small displays (≤128px): Use 50% inner radius with 60px outer radius
Medium displays (240px): Use 40-60% inner radius with 80px outer radius
Large displays (≥480px): Use any ratio with 100px+ outer radius for clarity

§Gauge Charts

Semicircle gauges with threshold zones and custom indicators:

use embedded_charts::prelude::*;
use embedded_graphics::pixelcolor::Rgb565;

let chart = GaugeChart::builder()
    .gauge_type(GaugeType::Semicircle)
    .value_range(0.0, 100.0)
    .add_threshold_zone(70.0, 100.0, Rgb565::RED)
    .build()?;
Ok(())

§Data Management

§Static Data Series

Fixed-capacity data storage for predictable memory usage:

use embedded_charts::prelude::*;

// Create a series with capacity for 256 points
let mut series: StaticDataSeries<Point2D, 256> = StaticDataSeries::new();
series.push(Point2D::new(0.0, 10.0))?;
series.push(Point2D::new(1.0, 20.0))?;

// Create from tuples using the macro
let data = data_points![(0.0, 10.0), (1.0, 20.0), (2.0, 15.0)];

§Multi-Series Data

Container for multiple data series with automatic color assignment:

use embedded_charts::prelude::*;

// Container for 8 series, 256 points each
let mut multi_series: MultiSeries<Point2D, 8, 256> = MultiSeries::new();

let temp_data = data_points![(0.0, 22.5), (1.0, 23.1), (2.0, 24.2)];
let humidity_data = data_points![(0.0, 65.0), (1.0, 68.0), (2.0, 72.0)];

multi_series.add_series(temp_data)?;
multi_series.add_series(humidity_data)?;

§Professional Styling

§Themes and Color Palettes

Built-in themes optimized for different display types:

use embedded_charts::prelude::*;

// Professional color palettes
let colors = quick::professional_colors();
let nature_colors = quick::nature_colors();
let ocean_colors = quick::ocean_colors();

// Complete themes
let light_theme = quick::light_theme();
let dark_theme = quick::dark_theme();
let cyberpunk_theme = quick::cyberpunk_theme();

§Chart Configuration

Fluent configuration with the chart_config! macro:

use embedded_charts::prelude::*;
use embedded_graphics::pixelcolor::Rgb565;

let config = chart_config! {
    title: "Temperature Monitor",
    background: Rgb565::WHITE,
    margins: constants::DEFAULT_MARGINS,
    grid: true,
};

§Real-time Animation

§Streaming Data (requires “animations” feature)

use embedded_charts::prelude::*;
use embedded_graphics::{prelude::*, pixelcolor::Rgb565};

// Sliding window for real-time data
let mut streaming_data: SlidingWindowSeries<Point2D, 100> =
    SlidingWindowSeries::new();

// Add data points (automatically removes old ones)
let timestamp = 1.0;
let value = 25.0;
streaming_data.push(Point2D::new(timestamp, value));

// Create a chart for rendering
let chart: LineChart<Rgb565> = LineChart::builder().build()?;
let config: ChartConfig<Rgb565> = ChartConfig::default();
let viewport = Rectangle::new(Point::zero(), Size::new(320, 240));
// chart.draw(&streaming_data, &config, viewport, &mut display)?;

§System Optimization

§Feature Configuration

Choose the appropriate feature set for your target system’s capabilities:

# Minimal configuration - Integer math only
[dependencies]
embedded-charts = {
    version = "0.1.0",
    default-features = false,
    features = ["integer-math"]
}

# Balanced configuration - Fixed-point math with color support
[dependencies]
embedded-charts = {
    version = "0.1.0",
    default-features = false,
    features = ["fixed-point", "color-support"]
}

# Full-featured configuration - All features enabled
[dependencies]
embedded-charts = {
    version = "0.1.0",
    default-features = false,
    features = ["floating-point", "animations", "color-support"]
}

§no_std Usage

Complete example for embedded systems:

#![no_std]

use embedded_charts::prelude::*;
use embedded_graphics::{pixelcolor::Rgb565, prelude::*};

fn render_sensor_chart() -> Result<(), embedded_charts::error::ChartError> {
    // Create data series with static allocation
    let mut sensor_data: StaticDataSeries<Point2D, 64> = StaticDataSeries::new();
    let _ = sensor_data.push(Point2D::new(0.0, 22.5));
    let _ = sensor_data.push(Point2D::new(1.0, 23.1));

    // Create minimal chart for small displays
    let chart = LineChart::builder()
        .line_color(Rgb565::BLUE)
        .build()?;

    // Render to embedded display
    let viewport = Rectangle::new(Point::zero(), Size::new(128, 64));
    // chart.draw(&sensor_data, chart.config(), viewport, &mut display)?;
    Ok(())
}

fn main() {
    let _ = render_sensor_chart();
}

§Complete Example

Professional multi-series chart:

use embedded_charts::prelude::*;
use embedded_graphics::{pixelcolor::Rgb565, prelude::*};

// Create sample data
let temp_data = data_points![(0.0, 22.5), (1.0, 23.1), (2.0, 24.2), (3.0, 23.8)];
let humidity_data = data_points![(0.0, 65.0), (1.0, 68.0), (2.0, 72.0), (3.0, 70.0)];

// Create multi-series container
let mut multi_series: MultiSeries<Point2D, 8, 256> = MultiSeries::new();
multi_series.add_series(temp_data)?;
multi_series.add_series(humidity_data)?;

// Create a simple line chart
let chart = LineChart::builder()
    .line_color(Rgb565::BLUE)
    .build()?;

// Configure the chart
let config: ChartConfig<Rgb565> = ChartConfig::default();

// Render to display
let viewport = Rectangle::new(Point::zero(), Size::new(320, 240));
// chart.draw(&multi_series, &config, viewport, &mut display)?;

§Module Organization

chart - Chart implementations (line, bar, pie, gauge, scatter)
data - Data series and point management
fluent - Fluent API for easy chart creation
style - Styling, themes, and color palettes
axes - Axis configuration and rendering
grid - Grid system for chart backgrounds
legend - Legend positioning and styling
animation - Real-time animations and transitions (feature-gated)
render - Low-level rendering primitives
layout - Chart layout and positioning
memory - Memory management utilities
time - Time abstraction for animations
math - Mathematical operations abstraction
error - Error types and handling
prelude - Convenient re-exports for common usage

For complete API documentation, see the API Documentation.

Re-exports§

pub use math::Math;
pub use math::Number;
pub use embedded_graphics;
pub use heapless;

Modules§

animation: Simplified animation system with external timeline control.
axes: Axis system for embedded graphics charts.
chart: Chart types and implementations.
config: Library configuration and feature detection
dashboard: Dashboard layout system for composing multiple charts
data: Data management module for chart data structures and operations.
error: Error types and result handling for the embedded graphics chart library.
fluent: Fluent API for creating charts with an intuitive, readable syntax.
grid: Grid system for embedded graphics charts.
heapless_utils: Heapless utilities and enhanced no_std support
layout: Layout management for chart components.
legend: Legend system for charts.
math: Math abstraction layer for no_std compatibility.
memory: Memory management utilities for embedded environments.
prelude: Convenience re-exports for common types and traits.
render: Rendering utilities for chart components.
style: Styling system for charts.
time: Time abstraction layer for animation systems.

Macros§

chart_config: Macro for creating chart configurations with a fluent syntax.
data_points: Utility macros for common operations
heapless_string: Create a heapless string with error handling
heapless_vec: Create a heapless vector from items

Constants§

VERSION: Current version of the library

Crate embedded_chartsCopy item path