PyDotNet.Matplotlib 1.0.0

PyDotNet.Matplotlib

A typed Matplotlib plugin for PyDotNet — render line, scatter, bar, and histogram charts to PNG, SVG, or PDF byte arrays from any .NET thread using the headless Agg backend.

Installation

dotnet add package PyDotNet.Matplotlib

Matplotlib must be installed in the active Python environment:

pip install matplotlib

Quick start

using PyDotNet.Matplotlib;
using PyDotNet.Runtime;

PyRuntime.Initialize(new PyRuntimeOptions { ReleaseGilAfterInit = true });

using var interp = PyRuntime.CreateInterpreter();
using var plt    = MatplotlibModule.Import(interp);

double[] x = [1, 2, 3, 4, 5];
double[] y = [2.1, 3.5, 2.8, 4.2, 3.9];

using var fig = plt.Figure(widthInches: 10, heightInches: 5);
fig.Axes.Plot(x, y, color: "steelblue", label: "Sensor A");
fig.Axes.SetTitle("Sensor readings");
fig.Axes.SetXLabel("Time (s)");
fig.Axes.SetYLabel("Value");
fig.Axes.Legend();
fig.Axes.Grid(true);

byte[] png = fig.SaveToPng(dpi: 150);
await File.WriteAllBytesAsync("chart.png", png);

PyRuntime.Shutdown();

Headless rendering

MatplotlibModule.Import activates the Agg backend before importing matplotlib.pyplot. The Agg backend renders entirely in-process to a memory buffer with no dependency on a display server or GUI toolkit. This makes it safe to use in web servers, background services, and containers.

The backend switch is idempotent: if Agg is already active it is a no-op.

API reference

MatplotlibModule

Figure

Axes

Plot types

Decorations

Examples

Line chart with two series

using var fig = plt.Figure();
fig.Axes.Plot(x, y1, color: "steelblue",  label: "Series A", lineStyle: "-");
fig.Axes.Plot(x, y2, color: "tomato",     label: "Series B", lineStyle: "--");
fig.Axes.SetTitle("Comparison");
fig.Axes.Legend();
fig.Axes.Grid(true);

byte[] png = fig.SaveToPng(dpi: 150);

Scatter chart

using var fig = plt.Figure();
fig.Axes.Scatter(xs, ys, color: "mediumseagreen", label: "Points");
fig.Axes.SetTitle("Scatter");
fig.Axes.Legend();
byte[] png = fig.SaveToPng();

Bar chart

string[] products = ["Apples", "Bananas", "Cherries"];
double[] sales    = [120, 85, 200];

using var fig = plt.Figure(widthInches: 8, heightInches: 5);
fig.Axes.Bar(products, sales, color: "coral");
fig.Axes.SetTitle("Fruit sales Q1");
fig.Axes.SetYLabel("Units");
byte[] png = fig.SaveToPng();

Histogram

using var fig = plt.Figure();
fig.Axes.Hist(data, bins: 30, color: "slateblue");
fig.Axes.SetTitle("Distribution");
byte[] png = fig.SaveToPng();

SVG / PDF export

byte[] svg = fig.SaveToSvg();
byte[] pdf = fig.SaveToPdf();
byte[] raw = fig.SaveToBytes("pdf", dpi: 300);

2-D heatmap

double[,] matrix = new double[8, 8];
for (int r = 0; r < 8; r++)
    for (int c = 0; c < 8; c++)
        matrix[r, c] = Math.Sin(r * 0.5) * Math.Cos(c * 0.5);

using var fig = plt.Figure(widthInches: 6, heightInches: 5);
fig.Axes.Imshow(matrix, colorMap: "plasma");
fig.Axes.SetTitle("Heatmap");
byte[] png = fig.SaveToPng();

Subplots grid

var (fig, axes) = plt.Subplots(rows: 2, cols: 2, widthInches: 12, heightInches: 8);

axes[0, 0].Plot(x, y1, color: "steelblue",  label: "Series A");
axes[0, 1].Scatter(x, y2, color: "tomato",   label: "Series B");
axes[1, 0].Bar(categories, values, color: "coral");
axes[1, 1].Hist(data, bins: 20, color: "slateblue");

fig.Tight();   // prevent label clipping
byte[] png = fig.SaveToPng(dpi: 150);

// Dispose axes before the figure
foreach (var ax in axes) ax.Dispose();
fig.Dispose();

Twin axes (dual y-axis)

using var fig = plt.Figure(widthInches: 10, heightInches: 5);
fig.Axes.Plot(x, temperature, color: "tomato", label: "Temp (°C)");
fig.Axes.SetYLabel("Temperature (°C)");

using var ax2 = fig.Axes.Twinx();
ax2.Plot(x, humidity, color: "steelblue", label: "Humidity (%)");
ax2.SetYLabel("Humidity (%)");

fig.Axes.SetTitle("Weather");
byte[] png = fig.SaveToPng();

Log scale

using var fig = plt.Figure();
fig.Axes.Plot(x, exponentialData, color: "darkorange");
fig.Axes.SetYScale("log");
fig.Axes.SetTitle("Exponential growth (log scale)");
byte[] png = fig.SaveToPng();

Python API coverage

~30 operations across MatplotlibModule, Figure, and Axes.

Notable gaps: color bars (colorbar), 3-D plots (Axes3D), animation, contour plots, custom tick formatters, and interactive backends.

Supported frameworks

net8.0 · net9.0 · net10.0