matplotlibnet

MatPlotLibNet — 面向 .NET 的 matplotlib

MatPlotLibNet 是一款适用于 C#、.NET 10 和 .NET 8 的绘图库，灵感来自 matplotlib。它可绘制 83 种图表，并能直接从服务器代码将图表保存为 SVG、PNG、PDF 或动画 GIF。它不需要 JavaScript 框架、WebView 或托管服务。

它拥有流畅的 API，并支持依赖注入。它附带 148 种色彩图、30 种主题、13 种内嵌 Natural Earth 数据的地图投影、LaTeX 风格的 MathText、支持任意文字体系的文本、包含 58 种技术指标的 O(1) 流式处理、控制室（Plt.OpsDashboard() — KPI 磁贴、状态时间线、共享趋势窗口），以及可供 AI Agent 使用的 MCP 服务。图表可原生渲染于 Blazor、WPF、MAUI、Avalonia、Uno 和 ASP.NET Core 中，也可渲染在 Verso 笔记本单元格内；此外还提供适用于 Angular、React 和 Vue 的 TypeScript 客户端。

发展方向

1.23.0 将读取蜡烛图开盘价、最高价、最低价、收盘价和成交量的技术指标，从单独的数组参数改为一个 OhlcvBars 值。该值通过工厂方法构建，方法名明确指出指标实际使用的列（OhlcvBars.Hlc(high, low, close)、OhlcvBars.Cv(close, volume) 等），不再需要在图表的每个指标中重复传入相同数组。现在，拥有两个以上刻度的图表也有地方放置额外刻度：WithOutwardYAxis 会在任意一侧将第二根轴叠放在第一根轴之外，总计支持四个刻度，左右各两个；每个刻度都有自己的范围、刻度线、系列和图例项，方式与 matplotlib 将双轴的轴脊向外移相同。次坐标轴也会像主坐标轴一样通过同一注册表还原，因此柱形图或面积图在次坐标轴和顶部轴上也能保留，而不仅限于折线或点图；无论是服务器响应手势还是原生控件处理，滚轮缩放、拖动平移、矩形缩放和 Home 现在都会移动所有这些坐标轴，且各自移动相应的量。在底层，流畅 API 用于构建图表的近百个动词现在分别位于独立文件中，作为 Axes 的扩展成员，而不再全部共用一个类——这只是文件布局的变更，不会改变读者编写的任何调用。

1.22.0 支持多个系列共用一种颜色，而不再各自从主题的循环中依次取色，并将此功能用于三个方面：Kaplan-Meier 曲线现在会以曲线自身的颜色绘制置信带和删失标记；两个新的动词 Raincloud（以一种颜色绘制半边小提琴图、窄箱线图和一组原始数据点）和 Horizon（将带正负值的系列折叠为两种色调的色带），使坐标轴构建器拥有了 17 个动词。

1.21.0 让每种图表类型和每项坐标轴设置都能完整地往返转换为 JSON。现在，Sankey 图的节点和链接、树图、旭日图、树状图和聚类图中的树结构、树形网格的行、极坐标图的数据、流式图表的当前数据点以及平面 3-D 柱状图的数据，都能从 JSON 还原为原本的内容，而不是占位符——MCP 服务现在会再次列出并接受全部八种图表，以前它会按名称拒绝它们。坐标轴的 Z 轴、3-D 面板颜色和工具提示开关也会还原。本次版本唯一尚未支持的系列是 MatPlotLibNet.Geo 的 GeoPolygonSeries，已列于路线图。 1.20.0 让原本需要一页代码绘制的图表只需一次调用。坐标轴构建器新增了 15 种绘图方法，其中包括 Pareto、Ridgeline、CalendarHeatmap、QQPlot、ControlChart、KaplanMeier、StreamGraph 和 Marimekko，它们直接使用现有数据（名称、分组、样本、日期）构建图表。 底层方面，现在将图形写入 JSON 后再读取，会还原出原样的图像及其绘制所需的所有设置，因此 MCP 服务和每种传输方式都能完整传递图形。NaN 是唯一的缺失值：与 matplotlib 一样，线条会在间隙处断开，NaN 处不会绘制任何内容。对数轴上的柱形会延伸到底边，水平柱形也能正常工作；类别名称会作为刻度标签，并为坐标轴标题留出空间；WithDpi 和 SaveOptions 现在也会应用到文件中。每个新增调用的代码示例都展示在 wiki 的示例页面上。

1.19.0 面向包含多条线和多个坐标轴的图表。WithDirectLabel() 会在线条末端以线条自身的颜色标注名称，而不是放在图例中；SetYAxisColor / SetXAxisColor 可通过一次调用为坐标轴着色，使其与对应线条匹配，左侧、底部、右侧和顶部坐标轴均适用。右侧和顶部坐标轴现在会遵循各自的刻度设置，在布局中获得专属空间，并在 JSON 中保留颜色；点击图例项时，这些坐标轴上的线条也会隐藏。在服务器交互式图表以及 WPF、Avalonia 和 Uno 控件中，悬停、选择、缩放、平移和数据光标都会报告读者看到的值，对数轴也不例外；设置的坐标轴范围，无论是否反向，都会精确对应实际绘制的范围。每个新增调用的代码示例都展示在 wiki 的示例页面上，而且 wiki 中的每个 C# 示例现在都可以编译。

此后，版本发布将根据社区需求推进：修复 Bug、完善文档，以及解决实际使用中遇到的各种问题。欢迎发起讨论或提交问题；下一版本将由此决定。每个版本及其迁移说明都列在 CHANGELOG 中；路线图说明已完成的内容、后续计划和有意排除的内容，wiki 的路线图页面还为每一项单独设有章节。

质量标准：每个类都必须通过严格的覆盖率门槛，即行覆盖率和分支覆盖率均 ≥90 %（848 个类，行覆盖率 99.7 % / 分支覆盖率 98.5 %），测试总数为 19,995 个。独立测试套件（Tst/MatPlotLibNet.Fidelity）会将渲染结果与 matplotlib 绘制的参考图像进行比较；它不属于 CI 运行的一部分。

---

文档

• Wiki — 入门指南、速查表、全部 83 种图表类型、控制室、样式设置、流式处理、SignalR、软件包
• 从 matplotlib 到 C# — 你熟悉的 pyplot 调用，以及在这里绘制图表的代码行
• 食谱 — 可直接复制粘贴并带有渲染结果的示例
• 体验场 — 在浏览器中实时试用图表
• API 参考 — 根据 XML 文档生成
• 路线图 — 已完成和后续计划的内容，按每一项所需的前置项目排序；wiki 的路线图页面说明每一项的工作内容以及有意排除的内容
• 基准测试 · 覆盖率政策 · 更新日志

---

软件包

软件包	安装	功能
MatPlotLibNet	dotnet add package MatPlotLibNet	核心功能：模型、流畅 API、SVG 渲染、JSON、变换
MatPlotLibNet.DataFrame	dotnet add package MatPlotLibNet.DataFrame	Microsoft.Data.Analysis.DataFrame 扩展方法——从命名列绘图、计算指标（SMA/EMA/RSI/MACD/…）和多项式回归
MatPlotLibNet.Skia	dotnet add package MatPlotLibNet.Skia	通过 SkiaSharp 导出 PNG、PDF 和动画 GIF
MatPlotLibNet.Blazor	dotnet add package MatPlotLibNet.Blazor	使用 SignalR 的 MplChart 和 MplLiveChart Razor 组件
MatPlotLibNet.AspNetCore	dotnet add package MatPlotLibNet.AspNetCore	REST 端点、SignalR hub、IChartPublisher
MatPlotLibNet.Interactive	dotnet add package MatPlotLibNet.Interactive	figure.ShowAsync()——弹出浏览器窗口，无需服务端
MatPlotLibNet.GraphQL	dotnet add package MatPlotLibNet.GraphQL	通过 HotChocolate 提供 GraphQL 查询和订阅
MatPlotLibNet.Maui	dotnet add package MatPlotLibNet.Maui	通过 Microsoft.Maui.Graphics 提供原生 MplChartView
MatPlotLibNet.Avalonia	dotnet add package MatPlotLibNet.Avalonia	适用于 Avalonia 12 的原生 MplChartControl——Skia 后端，可选本地交互
MatPlotLibNet.Uno	dotnet add package MatPlotLibNet.Uno	适用于 Uno Platform（WinUI 3 / Android / iOS / macCatalyst）的原生 MplChartElement
MatPlotLibNet.Wpf	dotnet add package MatPlotLibNet.Wpf	通过 SkiaSharp 提供原生 WPF MplChartControl——支持全部 15 种交互修饰器——以及用于实时数据的 MplStreamingChartControl；项目目标框架为 netX.0-windows10.0.19041.0
MatPlotLibNet.Geo	dotnet add package MatPlotLibNet.Geo	13 种地图投影、GeoJSON 解析器、Natural Earth 110m 数据、地理多边形
MatPlotLibNet.Verso	Verso → Extensions 面板	在 Verso notebook 单元格中绘制 SVG 图表（教程）
MatPlotLibNet.Notebooks	#r "nuget: MatPlotLibNet.Notebooks"	在 Polyglot / Jupyter notebook 中内嵌 SVG。Microsoft 已停止 Polyglot Notebooks 和 .NET Interactive 的开发，本软件包基于这两者构建，因此现有 notebook 仍可继续使用，但不会再有新功能——新项目请使用 MatPlotLibNet.Verso
MatPlotLibNet.Mcp	dnx MatPlotLibNet.Mcp	MCP 服务——AI Agent 通过 stdio 渲染图表（教程）
@matplotlibnet/angular	npm install @matplotlibnet/angular	Angular 组件 + TypeScript SignalR 客户端
@matplotlibnet/react	npm install @matplotlibnet/react	React hooks + 组件 + TypeScript SignalR 客户端
@matplotlibnet/vue	npm install @matplotlibnet/vue	Vue 3 composables + TypeScript SignalR 客户端

---

快速开始

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)
    .AddSubPlot(1, 1, 1, ax => ax
        .Plot(x, y, s => { s.Color = Colors.Blue; s.Label = "Data"; })
        .WithLegend())
    .Save("chart.svg");

---

功能特性

83 种系列类型——折线、散点（普通或按点密度着色）、柱状图（普通、堆叠，或一次调用即可按类别绘制多个组）、直方图、饼图、箱线图、小提琴图、热力图、等高线图、蜡烛图、OHLC、树状图、旭日图、Sankey、极坐标图、极坐标热力图、3D 曲面图、Bar3D、PlanarBar3D、Line3D、Trisurf3D、Contour3D、Quiver3D、Voxels、Text3D、雷达图、瀑布图、漏斗图、仪表盘、统计卡片（单值 KPI）、状态时间线（随时间变化的离散状态片段）、配对网格、相对旋转图、流式折线图/散点图/信号图/蜡烛图等。此外，还有 15 种一次调用即可生成的图表（Lollipop、Dumbbell、Pareto、SlopeGraph、DotPlot、ParallelCoordinates、Marimekko、Ridgeline、QQPlot、KaplanMeier、BumpChart、ControlChart、StreamGraph、CalendarHeatmap、Spy），它们由上述系列构建，因此不会增加系列类型的数量，并会在 JSON 中以其组成部分的形式传递。 MCP 服务 — 面向 AI Agent 的图表 — MatPlotLibNet.Mcp 是一个 Model Context Protocol 服务。它以 .NET 工具的形式提供，由主机通过 stdio 启动。它包含五个工具：render_chart（返回 PNG，以及对所绘内容的文本摘要）、save_chart （将 PNG/SVG/PDF 写入文件，并返回写入路径）、chart_data_table（以 markdown 格式返回绘图所依据的数值，单靠图像无法提供这些数据）、list_chart_types 和 describe_chart_schema。它采用库自身的图形 JSON 规范，因此 Agent 可以请求绘制库能绘制的任何内容。规范有误时，服务会在渲染前拒绝，并指出错误字段，而不是返回空白图片。参见 烹饪指南。

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

控制室 — Plt.OpsDashboard() 会构建一个操作员屏幕：顶部排列 KPI 磁贴，下方显示状态时间线，拓扑面板展示服务之间的调用关系（AddTopology），并配有共享趋势面板。所有面板使用调用方提供的同一时间窗口；库绝不会读取墙上时钟。每个磁贴都包含 Target、可自动换行的多行 Caption、内联迷你图，以及用于指明其状态的 OpsCondition。该状态刻意分为两个维度：只有 OpsSeverity（正常、警告、严重）会参与比较；OpsVisibility（已观测、未知、已搁置）则表示读数是否可信，以及是否有人将其静音——静默的数据源不代表服务降级，被静音的警报也不代表问题已解决。OpsCondition.RollUp 会像操作员一样读取一组子项：可见子项中最严重的状态决定颜色，同时统计不可见和已静音的子项。WithEventMarker 会在每个带时钟的面板上标记部署或事件。Theme.Alarm 定义了专用警报颜色，并附带四种操作员背景。BulletGraphSeries 可替代径向仪表。

原生 UI 控件 — Avalonia 12 的 MplChartControl 和 Uno Platform 的 MplChartElement 通过 SkiaSharp 原生渲染图表。它们无需浏览器、WebView 或 SignalR。共有 15 种交互修饰操作：平移（拖动）、缩放（滚动）、3D 旋转（右键拖动）、矩形缩放（Ctrl+拖动）、刷选（Shift+拖动）、区间选择（Alt+拖动）、图例切换（单击）、重置（双击、Home 或 Escape）、数据光标（单击数据点以固定光标）、趋势线、水平线和 Fibonacci 绘图工具、移除选中的绘图（Delete）、十字准线（被动）和悬停提示。这些控件还提供工具栏状态模型、视图历史记录（后退/前进）、刻度镜像和紧凑边距。单击数据点会触发 DataPointClicked，并传入读者所点击的点——包括系列、数值、像素位置和坐标轴——因此应用程序可以打开详细信息面板，或选中图表旁边的行。服务器驱动的图表会通过其 OnDataCursor 处理程序报告相同的点击事件。

MathText — 可在任意标签或标题中使用类 LaTeX 行内数学公式：$\alpha^{2}$、$\frac{a}{b}$、$\sqrt{x}$、$\hat{x}$、$\mathbf{F}$、$\mathbb{R}$。支持 96 种符号映射（希腊字母、数学运算符、箭头、关系符号、集合/逻辑符号、黑板粗体）、分数、平方根、重音符号、字体变体、间距和可缩放定界符。

国际化文本 — 标签、标题和图例条目支持任意文字系统。阿拉伯语和希伯来语可使用随附字体正常显示：Unicode 双向算法（UAX #9，覆盖全部 861,948 个一致性测试用例）会确定阅读方向，HarfBuzz 会对各文本段进行整形，再按视觉顺序排布这些文本段。SkiaFonts.Register(path) 可添加适用于天城文、泰文、中文及其他文字系统的字体文件；MCP 服务会从 MATPLOTLIBNET_FONTS 获取字体。同一整形流程会生成文本测量结果、SVG 字形轮廓和 PNG 像素。 3-D 图表 — 12 种系列类型：Surface、Wireframe、Scatter3D、Stem3D、Bar3D、PlanarBar3D、Line3D、Trisurf3D（Delaunay）、Contour3D（marching squares）、Quiver3D（矢量场）、Voxels（剔除背面后的立方体）、Text3D（注释）。3-D 支持包括完整的 Projection3D 渲染管线、DepthQueue3D 画家算法、基于 Vec3.FaceNormal 以及 Color.Shade()/Color.Modulate() 扩展方法的着色、用于客户端旋转并重新排序深度的 Svg3DRotationScript、根据相机确定的背面（CubeFaceSelection：无论方位角如何，面板、立方体边缘、墙面网格和刻度行都会跟随相机变化，服务端渲染和拖动过程中均如此）、可配置的 Pane3DConfig（地面／墙面颜色），以及 3D 色条支持。

流式处理与实时功能 — StreamingLineSeries、StreamingScatterSeries、StreamingSignalSeries 和 StreamingCandlestickSeries 均由 RingBuffer<T> 提供支持，并通过 AppendPoint(x, y) 添加点。RingBuffer<T> 是一种固定容量的任意类型循环序列（每秒可追加 6400 万次，且追加时不会分配内存）。StreamingFigure 提供节流重绘和自动缩放坐标轴（SlidingWindow、StickyRight、AutoScale）。11 种流式指标（SMA、EMA、RSI、Bollinger、MACD、OBV、ATR、Stochastic、WilliamsR、CCI、VWAP）会自动附加到烛台数据。WPF、Avalonia、Uno、MAUI、Blazor 和 ASP.NET Core 均提供流式控件。该库包含用于节省带宽的 SVG 差异引擎，以及 Rx IObservable<T> 适配器。

地理投影 — MatPlotLibNet.Geo 包含 13 种地图投影（PlateCarree、Mercator、TransverseMercator、Robinson、Orthographic、LambertConformal、AlbersEqualArea、AzimuthalEquidistant、EqualEarth、Mollweide、Natural Earth、Sinusoidal、Stereographic）、GeoJSON 解析器、内嵌的 Natural Earth 110m 数据，以及用于海岸线、边界和分级统计地图的 GeoPolygonSeries。symlog 坐标轴刻度可处理跨越正负范围的数据。

双向 SignalR — 由服务端控制的交互式图表，支持变更事件（缩放、平移、重置、切换图例）和通知事件（框选、悬停、点击的数据点）。事件构成一个堆叠记录层级，能够自动合并，且服务端会向每位调用者发送各自的悬停响应。

无障碍访问 — figure.ToDataTables() 会为每张图表在图片旁提供数据表（ToHtml()、ToMarkdown()、ToCsv()）。对于复杂图像，该表格是 WCAG 1.1.1 要求的文本替代内容，单靠 <svg role="img"> 无法提供。可通过 MapChartTableEndpoint、MplChart.ShowDataTable、GraphQL 的 chartDataTable 字段和 MCP 的 chart_data_table 工具获取该表格；后者会以 Markdown 格式返回表格供阅读，也会返回结构化值供计算使用。该库还提供 ARIA 角色和标题、键盘导航、适合色盲人士的 Okabe-Ito 配色方案、三种 Petroff 无障碍配色序列，以及高对比度主题。

148 种色图 — viridis、plasma、turbo、coolwarm 等，以及另外 144 种（74 种基础色图，均自动注册反转的 _r 变体）。该库还提供 NumPy 风格的 SIMD 数值运算（Vec、Mat、Linalg、Fft）、matplotlib 风格的主题、集成 58 种技术指标的 DataFrame 支持、断轴，以及适用于出版物的 SVG/PNG/PDF/GIF 导出。

---

许可证

MIT — 可免费用于任何用途，无论是开源还是商业用途，且没有 copyleft 条款。