SadConsole.Charts

ASCII data visualization library for SadConsole. Bar charts, line charts, sparklines, scatter plots, heatmaps, and dashboard grid layouts using Unicode block elements and box-drawing characters.

Built for game dev HUDs, post-game stats screens, and developer tool dashboards.

Chart Types

Type	Element Class	Visual Style
Horizontal Bar	HorizontalBarElement	Block fill with fractional precision
Line	LineElement	Box-drawing connectors with markers
Sparkline	SparklineElement	Compact 1-row block elements
Scatter	ScatterElement	Point markers with sub-cell support
Heatmap	HeatmapElement	Shade glyphs with color gradient
Area Fill	AreaFillElement	Shade-fill (░▒▓) below a line for area chart effect
Sparkline Bar	SparklineBarElement	Composite label + inline sparkline + value suffix, one row per entry
Annotation	AnnotationElement	Labeled markers at data coordinates (floor transitions, events)

Quick Start

using SadConsole.Charts.Data;
using SadConsole.Charts.Elements;
using SadConsole.Charts.Widgets;
using SadRogue.Primitives;

// Bar chart
var bars = new HorizontalBarElement
{
    Label = "Tower Damage",
    Color = Color.Cyan,
    Bars = [
        new BarEntry("Arrow III", 4523),
        new BarEntry("Fire II", 3102),
        new BarEntry("Ice I", 2441),
    ]
};

var chart = new ChartSurface(60, 20)
    .WithTitle("TOWER DAMAGE")
    .AddElement(bars);

parentScreen.Children.Add(chart);

// Sparkline (1 row tall)
var spark = new SparklineSurface(40, Color.Gold)
    .WithLabel("DPS: ")
    .SetValues([10, 25, 40, 55, 70, 65, 80, 95]);

parentScreen.Children.Add(spark);

Architecture

src/SadConsole.Charts/
  Data/        14 DTOs, zero logic, SadConsole-independent
  Pipeline/    Scales, ticks, layout, cell mapping — fully testable
  Elements/    Chart type implementations
  Rendering/   Thin SadConsole bridge — only layer that writes cells
  Widgets/     Top-level ScreenSurface types (ChartSurface, SparklineSurface, DashboardSurface)

The library uses an 8-phase rendering pipeline:

1. UpdateData - Elements refresh derived state
2. GetBounds - Merge data extents across elements
3. FinalizeScales - Create IScale from bounds + axis overrides
4. GenerateTicks - NiceTickGenerator (Heckbert's algorithm)
5. MeasureLayout - Outside-in gutter allocation
6. CreateCellMapper - Data-to-cell coordinate mapping
7. EmitDrawCommands - Elements emit DrawCommand structs (no allocation)
8. Execute - SurfaceRenderer writes glyphs to ICellSurface

New data types: Annotation (record struct + AnnotationPosition enum for labeled chart markers), SparklineBarEntry (record struct for sparkline-bar charts: label + values + total).

Data/ and Pipeline/ have zero SadConsole imports and can be tested in isolation.

Dashboard Layout

var dashboard = new DashboardSurface(120, 40, rows: 2, cols: 3);
dashboard.Set(0, 0, rowSpan: 1, colSpan: 2, lineChart);
dashboard.Set(0, 2, barChart);
dashboard.Set(1, 0, heatmap);
dashboard.Set(1, 1, rowSpan: 1, colSpan: 2, sparklinePanel);

Font Compatibility

The library works with standard CP437 fonts (the SadConsole default). GlyphTable uses CP437 indices:

• Box-drawing: thin lines (CP437 196, 179, 218, etc.)
• Shades: light/medium/dark (CP437 176, 177, 178)
• Blocks: full, half (CP437 219, 220, 221, 222, 223)
• Markers: MiddleDot, TriangleDown, TriangleUp (used by annotations and legends)

For fonts with full Unicode coverage, block elements provide 8-level vertical/horizontal resolution.

Recent Changes

• LineElement — ColorFunction property for per-point gradient coloring (e.g. HP green→red)
• AxisRenderer — RenderGrid() for dotted grid lines, RenderLegend() for multi-element legends

Requirements

• .NET 9.0+
• SadConsole 10.8+

Building

dotnet build SadConsole.Charts.sln
dotnet test

Running the Demo

cd samples/SadConsole.Charts.Demo
dotnet run

License

MIT - see LICENSE.