MatPlotLibNet

# MatPlotLibNet — matplotlib for .NET

MatPlotLibNet is a charting library for C#, .NET 10 and .NET 8, inspired by
[matplotlib](https://matplotlib.org/). It draws 83 chart types and saves them as SVG, PNG, PDF or an animated GIF,
straight from your server code. It does not need a JavaScript framework, a WebView or a hosted service.

It has a fluent API and it works with dependency injection. It ships with 148 colormaps, 30 themes, 13 map
projections with embedded Natural Earth data, LaTeX-style MathText, text in any script, O(1) streaming with 53
technical indicators, a control room (`Plt.OpsDashboard()` — KPI tiles, state timelines, one shared trend window),
and an MCP server so an AI agent can draw with it. Charts render natively in Blazor, WPF, MAUI, Avalonia, Uno and
ASP.NET Core, and TypeScript clients are there for Angular, React and Vue.

[![CI](https://github.com/xkqg/MatPlotLibNet/actions/workflows/ci.yml/badge.svg)](https://github.com/xkqg/MatPlotLibNet/actions/workflows/ci.yml)
[![NuGet](https://img.shields.io/nuget/v/MatPlotLibNet)](https://www.nuget.org/packages/MatPlotLibNet)
[![NuGet Downloads](https://img.shields.io/nuget/dt/MatPlotLibNet)](https://www.nuget.org/packages/MatPlotLibNet)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/xkqg/MatPlotLibNet)](https://github.com/xkqg/MatPlotLibNet)

## Where this is going

**1.17** draws text in any script. Arabic letters join, Hebrew reads right to left, and a number or a Latin word
inside Arabic or Hebrew text is placed in the correct position, using the font that ships in the package. The
Unicode bidi algorithm is implemented in full and checked against Unicode's own 861,948 test cases; HarfBuzz shapes
each run. Other scripts need a font file: `SkiaFonts.Register(path)` registers one, and the MCP server reads font
files from the `MATPLOTLIBNET_FONTS` variable. Latin text is now kerned too, so text widths changed by up to 2 px
per letter pair.

**1.16** adds a data table beside every chart, for a reader who cannot see the picture.
`figure.ToDataTables()` returns the figure's data as tables with typed columns, and you can write each table
as HTML, Markdown or CSV. Every host serves the table: an ASP.NET Core endpoint next to the SVG endpoint, a
`ShowDataTable` option on the Blazor component, a `chartDataTable` field in the GraphQL schema, and a fifth MCP
tool. The same release fixed the streaming series. A point and a candle are now stored as one value, so a snapshot
can no longer show a point or a bar that never existed. The buffer behind them is now the generic `RingBuffer<T>`.

**1.15** added support for AI agents. `MatPlotLibNet.Mcp` is a Model Context Protocol server. A model can render
any of these chart types from a JSON spec and look at the result. When the spec is wrong, the server reports which
field is wrong instead of returning a blank picture.

**1.14** added the control room: `Plt.OpsDashboard()` and the tile anatomy arrived with it. The releases since
then contain the fixes and extensions that real control-room use required: a secondary Y axis with the same
capabilities as the primary axis, streaming that draws in SVG, 3-D axis titles that do not overlap their own
labels, tile captions that wrap and stay inside their tile, and an ops window whose ticks are formatted as time.

After that, releases follow what the community needs: bug fixes, documentation, and whatever comes up in real use.
Open a [Discussion](https://github.com/xkqg/MatPlotLibNet/discussions) or an
[Issue](https://github.com/xkqg/MatPlotLibNet/issues); that is what decides the next release. Every release, with
its migration notes, is listed in the [CHANGELOG](CHANGELOG.md).

Quality bar: every class must pass a strict coverage gate of ≥90 % line and branch coverage (706 classes, at
99.6 % line / 97.5 % branch) across 11,757 tests. The test suite verifies rendering against matplotlib
pixel-fidelity fixtures.

---

## Documentation

- **[Wiki](https://github.com/xkqg/MatPlotLibNet/wiki)** — getting started, cheatsheet, all 83 chart types, the
  control room, styling, streaming, SignalR, packages
- **[Cookbook](https://xkqg.github.io/MatPlotLibNet/cookbook/)** — copy-paste examples with rendered output
- **[Playground](https://xkqg.github.io/MatPlotLibNet/playground/)** — try charts live in the browser
- **[API Reference](https://xkqg.github.io/MatPlotLibNet/api/)** — generated from the XML docs
- **[Benchmarks](BENCHMARKS.md)** · **[Coverage policy](docs/COVERAGE.md)** · **[CHANGELOG](CHANGELOG.md)**

---

## Packages

| Package | Install | What it does |
|---|---|---|
| **MatPlotLibNet** | `dotnet add package MatPlotLibNet` | Core: models, fluent API, SVG rendering, JSON, transforms |
| **[MatPlotLibNet.DataFrame](https://www.nuget.org/packages/MatPlotLibNet.DataFrame)** | `dotnet add package MatPlotLibNet.DataFrame` | `Microsoft.Data.Analysis.DataFrame` extension methods — plot, indicators (SMA/EMA/RSI/MACD/…), and polynomial regression from named columns |
| **MatPlotLibNet.Skia** | `dotnet add package MatPlotLibNet.Skia` | PNG, PDF, and animated GIF export via SkiaSharp |
| **MatPlotLibNet.Blazor** | `dotnet add package MatPlotLibNet.Blazor` | `MplChart` + `MplLiveChart` Razor components with SignalR |
| **MatPlotLibNet.AspNetCore** | `dotnet add package MatPlotLibNet.AspNetCore` | REST endpoints, SignalR hub, `IChartPublisher` |
| **MatPlotLibNet.Interactive** | `dotnet add package MatPlotLibNet.Interactive` | `figure.ShowAsync()` — browser popup, no server needed |
| **MatPlotLibNet.GraphQL** | `dotnet add package MatPlotLibNet.GraphQL` | GraphQL queries + subscriptions via HotChocolate |
| **MatPlotLibNet.Maui** | `dotnet add package MatPlotLibNet.Maui` | Native `MplChartView` via Microsoft.Maui.Graphics |
| **MatPlotLibNet.Avalonia** | `dotnet add package MatPlotLibNet.Avalonia` | Native `MplChartControl` for Avalonia 12 — Skia backend, optional local interaction |
| **MatPlotLibNet.Uno** | `dotnet add package MatPlotLibNet.Uno` | Native `MplChartElement` for Uno Platform (WinUI 3 / Android / iOS / macCatalyst) |
| **MatPlotLibNet.Wpf** | `dotnet add package MatPlotLibNet.Wpf` | Native WPF `MplChartControl` via SkiaSharp — all 9 interaction modifiers |
| **MatPlotLibNet.Geo** | `dotnet add package MatPlotLibNet.Geo` | 13 map projections, GeoJSON parser, Natural Earth 110m data, geographic polygons |
| **MatPlotLibNet.Notebooks** | `#r "nuget: MatPlotLibNet.Notebooks"` | Inline SVG in Polyglot / Jupyter notebooks. Microsoft has ended Polyglot Notebooks and .NET Interactive, which this package builds on, so existing notebooks keep working but nothing new is coming — for new work use **MatPlotLibNet.Interactive** |
| **[MatPlotLibNet.Mcp](https://www.nuget.org/packages/MatPlotLibNet.Mcp)** | `dnx MatPlotLibNet.Mcp` | MCP server — an AI agent renders charts over stdio ([cookbook](docs/cookbook/mcp.md)) |
| **@matplotlibnet/angular** | `npm install @matplotlibnet/angular` | Angular components + TypeScript SignalR client |
| **@matplotlibnet/react** | `npm install @matplotlibnet/react` | React hooks + components + TypeScript SignalR client |
| **@matplotlibnet/vue** | `npm install @matplotlibnet/vue` | Vue 3 composables + TypeScript SignalR client |

---

## Quick start

```csharp
using MatPlotLibNet;
using MatPlotLibNet.Styling;

double[] x = [1, 2, 3, 4, 5];
double[] y = [2, 4, 3, 5, 1];

Plt.Create()
    .WithTitle("My First Chart")
    .WithTheme(Theme.Dark)
    .Plot(x, y, s => { s.Color = Color.Blue; s.Label = "Data"; })
    .WithLegend()
    .Save("chart.svg");
```

---

## Features

**83 series types** — line, scatter (plain or coloured by point density), bar (plain, stacked, or several groups per category in one call), histogram, pie, box, violin, heatmap, contour, candlestick, OHLC, treemap, sunburst, Sankey, polar, polar heatmap, 3D surface, Bar3D, PlanarBar3D, Line3D, Trisurf3D, Contour3D, Quiver3D, Voxels, Text3D, radar, waterfall, funnel, gauge, stat tile (single-value KPI), state timeline (discrete state segments over time), pair grid, relative rotation graph, streaming line/scatter/signal/candlestick, and more.

**MCP server — charts for an AI agent** — `MatPlotLibNet.Mcp` is a
[Model Context Protocol](https://modelcontextprotocol.io) server. It ships as a .NET tool that a host starts over
stdio. It has five tools: `render_chart` (returns a PNG plus a text summary of what was drawn), `save_chart`
(writes PNG/SVG/PDF to a file and returns the path it wrote), `chart_data_table` (returns the numbers the picture
is drawn from, as markdown, which an image alone cannot give), `list_chart_types` and `describe_chart_schema`. The
spec is the library's own figure JSON, so an agent can ask for anything the library draws. When a spec is wrong,
the server rejects it before rendering and names the wrong field, instead of returning a blank picture. See the
[cookbook](docs/cookbook/mcp.md).

```json
{ "servers": { "MatPlotLibNet.Mcp": { "type": "stdio", "command": "dnx", "args": ["MatPlotLibNet.Mcp", "--yes"] } } }
```

**Control room** — `Plt.OpsDashboard()` builds one operator screen: KPI tiles across the top, state timelines under them, a topology panel showing which service calls which (`AddTopology`), and a shared trend panel. All of them use one time window that the caller supplies; the library never reads the wall clock. A tile carries a `Target`, a multi-line `Caption` that wraps, an inline sparkline and a `Hatch` that means *no information*. `Theme.Alarm` defines the reserved alarm colours, and four operator backgrounds ship with it. `BulletGraphSeries` replaces the radial gauge.

**Native UI controls** — [`MplChartControl`](https://github.com/xkqg/MatPlotLibNet/wiki/Interactive-Controls) for Avalonia 12 and [`MplChartElement`](https://github.com/xkqg/MatPlotLibNet/wiki/Interactive-Controls) for Uno Platform render charts natively via SkiaSharp. They need no browser, no WebView