MatPlotLibNet

MatPlotLibNet — matplotlib para .NET

MatPlotLibNet é uma biblioteca de gráficos para C#, .NET 10 e .NET 8, inspirada em matplotlib. Ela desenha 83 tipos de gráfico e os salva como SVG, PNG, PDF ou um GIF animado, diretamente do seu código de servidor. Não precisa de um framework JavaScript, de uma WebView nem de um serviço hospedado.

Tem uma API fluente e funciona com injeção de dependência. Vem com 148 mapas de cores, 30 temas, 13 projeções cartográficas com dados Natural Earth embutidos, MathText no estilo LaTeX, texto em qualquer alfabeto, streaming O(1) com 58 indicadores técnicos, uma sala de controle (Plt.OpsDashboard() — tiles de KPI, linhas do tempo de estado, uma janela de tendência compartilhada), e um servidor MCP para que um agente de IA possa desenhar com ela. Os gráficos são renderizados nativamente em Blazor, WPF, MAUI, Avalonia, Uno e ASP.NET Core, dentro de uma célula de notebook Verso, e há clientes TypeScript para Angular, React e Vue.

Para onde isso está indo

1.23.0 move os indicadores técnicos que leem a abertura, a máxima, a mínima, o fechamento e o volume de um candle de parâmetros de array separados para um único valor OhlcvBars, construído com a fábrica que nomeia as colunas que o indicador realmente usa (OhlcvBars.Hlc(high, low, close), OhlcvBars.Cv(close, volume), e assim por diante) em vez de repetir os mesmos arrays em cada indicador de um gráfico. Um gráfico com mais de duas escalas agora tem onde colocar as extras: WithOutwardYAxis empilha um segundo eixo depois do primeiro em qualquer um dos lados — quatro escalas no total, duas à esquerda e duas à direita, cada uma com seu próprio intervalo, ticks, séries e entrada de legenda, do jeito que o matplotlib move a espinha de um gêmeo para fora. Um eixo secundário é restaurado pelo mesmo registro que o primário, então uma barra ou uma área sobrevive ali e no eixo superior também, não apenas uma linha ou um ponto; e um zoom com a roda, um arrasto de pan, um zoom retangular e Home agora movem cada um desses eixos, cada um pela sua própria quantidade, seja o servidor respondendo ao gesto ou um controle nativo. Por baixo, a quase centena de verbos de gráfico a partir dos quais a API fluente é construída agora vivem um por arquivo como membros de extensão em Axes em vez de todos compartilharem uma única classe — uma mudança apenas de layout de arquivos, nenhuma chamada que o leitor escreve é diferente por causa disso.

1.22.0 permite que várias séries compartilhem uma cor em vez de cada uma pegar a próxima do ciclo do tema, e gasta isso em três coisas: uma curva de Kaplan-Meier agora desenha sua faixa de confiança e suas marcas de censura na cor da própria curva, e dois novos verbos, Raincloud (um meio violino, uma caixa estreita e os pontos brutos de um grupo em uma cor) e Horizon (uma série com sinal dobrada em faixas de duas matizes), levam o construtor de eixos a dezessete verbos.

1.21.0 faz com que cada tipo de gráfico e cada configuração de eixos façam round-trip completo por JSON. Os nós e links de um Sankey, as árvores de um treemap, sunburst, dendrograma e clustermap, as linhas de uma grade de árvore, os dados de um gráfico polar, os pontos atuais de um gráfico de streaming e os dados de uma barra 3-D planar agora voltam do JSON como eles mesmos, não um placeholder — o servidor MCP lista e aceita todos os oito de novo, onde antes os recusava pelo nome. O eixo Z de um eixo, as cores de painel 3-D e o interruptor de tooltip também voltam. A única série que esta versão não alcançou é o GeoPolygonSeries de MatPlotLibNet.Geo, nomeado no roadmap.

1.20.0 transforma gráficos que tomavam uma página de código em uma única chamada. Quinze verbos no construtor de eixos, entre eles Pareto, Ridgeline, CalendarHeatmap, QQPlot, ControlChart, KaplanMeier, StreamGraph e Marimekko, recebem os dados como você os tem (nomes, grupos, amostras, datas) e constroem o gráfico a partir das séries que a biblioteca já tem. Por baixo deles, uma figura escrita em JSON agora é lida de volta como a imagem que era, com cada configuração que ela desenha, então o servidor MCP e cada transporte a carregam inteira. NaN é o único valor ausente: uma linha se quebra em uma lacuna, como no matplotlib, e nada é desenhado em NaN. Barras em um eixo logarítmico alcançam a borda inferior, barras horizontais funcionam, nomes de categoria são rótulos de tick com espaço para o título do eixo, e WithDpi e SaveOptions agora chegam ao arquivo. Cada nova chamada é mostrada em código na página de exemplos da wiki.

1.19.0 é para gráficos com mais de uma linha e mais de um eixo. WithDirectLabel() escreve o nome de uma linha no seu final, na cor da própria linha, em vez de na legenda, e SetYAxisColor / SetXAxisColor colorem um eixo para combinar com sua linha em uma única chamada, no eixo esquerdo, inferior, direito e superior igualmente. Os eixos direito e superior agora seguem suas próprias configurações de tick, ganham espaço próprio no layout e mantêm suas cores por JSON, e uma linha neles se esconde quando sua entrada de legenda é clicada. Em um gráfico interativo no servidor e nos controles WPF, Avalonia e Uno, hover, seleção, zoom, pan e o cursor de dados relatam os valores que o leitor vê, também em eixos logarítmicos, e um limite de eixo que você define, invertido ou não, agora é exatamente o intervalo desenhado. Cada nova chamada é mostrada em código na página de exemplos da wiki, e cada exemplo em C# da wiki agora compila.

Depois disso, as versões seguem o que a comunidade precisa: correções de bugs, documentação e o que surgir no uso real. Abra uma Discussion ou uma Issue; é isso que decide a próxima versão. Cada versão, com suas notas de migração, está listada no CHANGELOG, e o roadmap diz o que está feito, o que ainda está por vir e o que foi deixado de fora de propósito, com uma seção para cada linha na página da wiki.

Padrão de qualidade: cada classe deve passar por um gate de cobertura estrito de ≥90 % de cobertura de linhas e ramos (848 classes, a 99,7 % de linhas / 98,5 % de ramos) em 19.995 testes. Uma suíte separada (Tst/MatPlotLibNet.Fidelity) compara a renderização com imagens de referência desenhadas pelo matplotlib; ela não faz parte da execução de CI.

---

Documentação

• Wiki — primeiros passos, cheatsheet, todos os 83 tipos de gráfico, a sala de controle, estilização, streaming, SignalR, pacotes
• De matplotlib para C# — a chamada pyplot que você conhece, e a linha que a desenha aqui
• Cookbook — exemplos para copiar e colar com saída renderizada
• Playground — experimente gráficos ao vivo no navegador
• Referência da API — gerada a partir dos docs XML
• Roadmap — o que está feito e o que ainda está por vir, na ordem em que cada linha precisa da de cima; a página da wiki diz o que cada linha exige e o que foi deixado de fora de propósito
• Benchmarks · Política de cobertura · CHANGELOG

---

Pacotes

Pacote	Instalação	O que faz
MatPlotLibNet	dotnet add package MatPlotLibNet	Núcleo: modelos, API fluente, renderização SVG, JSON, transformações
MatPlotLibNet.DataFrame	dotnet add package MatPlotLibNet.DataFrame	Métodos de extensão de Microsoft.Data.Analysis.DataFrame — plot, indicadores (SMA/EMA/RSI/MACD/…), e regressão polinomial a partir de colunas nomeadas
MatPlotLibNet.Skia	dotnet add package MatPlotLibNet.Skia	Exportação de PNG, PDF e GIF animado via SkiaSharp
MatPlotLibNet.Blazor	dotnet add package MatPlotLibNet.Blazor	Componentes Razor MplChart + MplLiveChart com SignalR
MatPlotLibNet.AspNetCore	dotnet add package MatPlotLibNet.AspNetCore	Endpoints REST, hub SignalR, IChartPublisher
MatPlotLibNet.Interactive	dotnet add package MatPlotLibNet.Interactive	figure.ShowAsync() — popup no navegador, sem precisar de servidor
MatPlotLibNet.GraphQL	dotnet add package MatPlotLibNet.GraphQL	Consultas + assinaturas GraphQL via HotChocolate
MatPlotLibNet.Maui	dotnet add package MatPlotLibNet.Maui	MplChartView nativo via Microsoft.Maui.Graphics
MatPlotLibNet.Avalonia	dotnet add package MatPlotLibNet.Avalonia	MplChartControl nativo para Avalonia 12 — backend Skia, interação local opcional
MatPlotLibNet.Uno	dotnet add package MatPlotLibNet.Uno	MplChartElement nativo para Uno Platform (WinUI 3 / Android / iOS / macCatalyst)
MatPlotLibNet.Wpf	dotnet add package MatPlotLibNet.Wpf	MplChartControl nativo do WPF via SkiaSharp — todos os 15 modificadores de interação — e MplStreamingChartControl para dados ao vivo; seu projeto tem como alvo netX.0-windows10.0.19041.0
MatPlotLibNet.Geo	dotnet add package MatPlotLibNet.Geo	13 projeções cartográficas, parser GeoJSON, dados Natural Earth 110m, polígonos geográficos
MatPlotLibNet.Verso	Verso → painel Extensions	Um gráfico dentro de uma célula de notebook Verso, desenhado como SVG (cookbook)
MatPlotLibNet.Notebooks	#r "nuget: MatPlotLibNet.Notebooks"	SVG inline em notebooks Polyglot / Jupyter. A Microsoft encerrou o Polyglot Notebooks e o .NET Interactive, nos quais este pacote se baseia, então os notebooks existentes continuam funcionando, mas nada novo virá — para novos trabalhos use MatPlotLibNet.Verso
MatPlotLibNet.Mcp	dnx MatPlotLibNet.Mcp	Servidor MCP — um agente de IA renderiza gráficos via stdio (cookbook)
@matplotlibnet/angular	npm install @matplotlibnet/angular	Componentes Angular + cliente SignalR TypeScript
@matplotlibnet/react	npm install @matplotlibnet/react	Hooks + componentes React + cliente SignalR TypeScript
@matplotlibnet/vue	npm install @matplotlibnet/vue	Composables Vue 3 + cliente SignalR TypeScript

---

Início rápido

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");

---

Recursos

83 tipos de série — linha, dispersão (simples ou colorida pela densidade de pontos), barra (simples, empilhada ou vários grupos por categoria em uma única chamada), histograma, pizza, caixa, violino, heatmap, contorno, candlestick, OHLC, treemap, sunburst, Sankey, polar, heatmap polar, superfície 3D, Bar3D, PlanarBar3D, Line3D, Trisurf3D, Contour3D, Quiver3D, Voxels, Text3D, radar, waterfall, funil, gauge, tile de estatística (KPI de valor único), linha do tempo de estado (segmentos de estado discretos ao longo do tempo), grade de pares, gráfico de rotação relativa, linha/dispersão/sinal/candlestick em streaming, e mais. Sobre eles, quinze gráficos de uma chamada (Lollipop, Dumbbell, Pareto, SlopeGraph, DotPlot, ParallelCoordinates, Marimekko, Ridgeline, QQPlot, KaplanMeier, BumpChart, ControlChart, StreamGraph, CalendarHeatmap, Spy) são construídos a partir dessas séries, então não acrescentam nenhum à contagem e trafegam por JSON como suas partes.

Servidor MCP — gráficos para um agente de IA — MatPlotLibNet.Mcp é um servidor Model Context Protocol. Ele é distribuído como uma ferramenta .NET que um host inicia via stdio. Tem cinco ferramentas: render_chart (retorna um PNG mais um resumo em texto do que foi desenhado), save_chart (grava PNG/SVG/PDF em um arquivo e retorna o caminho gravado), chart_data_table (retorna os números a partir dos quais a imagem é desenhada, como markdown, o que uma imagem sozinha não consegue dar), list_chart_types e describe_chart_schema. A especificação é o próprio JSON de figura da biblioteca, então um agente pode pedir qualquer coisa que a biblioteca desenhe. Quando uma especificação está errada, o servidor a rejeita antes de renderizar e nomeia o campo errado, em vez de retornar uma imagem em branco. Veja o cookbook.

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

Sala de controle — Plt.OpsDashboard() monta uma única tela de operador: tiles de KPI no topo, linhas do tempo de estado abaixo deles, um painel de topologia mostrando qual serviço chama qual (AddTopology) e um painel de tendência compartilhado. Todos usam uma única janela de tempo fornecida pelo chamador; a biblioteca nunca lê o relógio do sistema. Um tile carrega um Target, um Caption multilinha que quebra automaticamente, uma sparkline inline e um OpsCondition dizendo em que estado ele está. Essa condição tem dois eixos de propósito: OpsSeverity (normal, warning, critical) é o único que compara, e OpsVisibility (observed, unknown, shelved) diz se a leitura pode ser acreditada e se alguém a silenciou — uma fonte silenciosa não é uma fonte degradada, e um alarme silenciado não é um problema resolvido. OpsCondition.RollUp lê um conjunto de filhos como um operador faz: o pior filho visível decide a cor, e os não vistos e os silenciados são contados. WithEventMarker coloca um deploy ou um incidente em todos os painéis que têm um relógio. Theme.Alarm define as cores de alarme reservadas, e quatro fundos de operador vêm com ele. BulletGraphSeries substitui o medidor radial.

Controles de UI nativos — MplChartControl para Avalonia 12 e MplChartElement para Uno Platform renderizam gráficos nativamente via SkiaSharp. Eles não precisam de navegador, WebView nem SignalR. Há 15 modificadores de interação: pan (arrastar), zoom (rolar), rotação 3D (arrastar com o botão direito), zoom retangular (Ctrl+arrastar), seleção por pincel (Shift+arrastar), seleção de intervalo (Alt+arrastar), alternância de legenda (clique), reset (duplo clique, Home ou Escape), cursor de dados (clique em um ponto para fixá-lo), as ferramentas de desenho de linha de tendência, nível e Fibonacci, remoção de um desenho selecionado (Delete), crosshair (passivo) e tooltip ao passar o mouse. Os controles também têm um modelo de estado de barra de ferramentas, histórico de visualização (voltar/avançar), espelhamento de ticks e margens justas. Clicar em um ponto de dados dispara DataPointClicked com o ponto em que o leitor clicou — série, valor, posição em pixels e eixos — para que uma aplicação possa abrir um painel de detalhes ou selecionar uma linha ao lado do gráfico. Um gráfico controlado pelo servidor reporta o mesmo clique ao seu handler OnDataCursor.

MathText — matemática inline no estilo LaTeX em qualquer rótulo ou título: $\alpha^{2}$, $\frac{a}{b}$, $\sqrt{x}$, $\hat{x}$, $\mathbf{F}$, $\mathbb{R}$. Suporta 96 mapeamentos de símbolos (grego, operadores matemáticos, setas, relações, conjuntos/lógica, blackboard bold), frações, raízes quadradas, acentos, variantes de fonte, espaçamento e delimitadores escaláveis.

Texto internacional — rótulos, títulos e entradas de legenda em qualquer escrita. Árabe e hebraico funcionam com a fonte incluída: o algoritmo bidi do Unicode (UAX #9, todos os 861.948 casos de conformidade) determina a direção de leitura, o HarfBuzz modela cada trecho e os trechos são dispostos em ordem visual. SkiaFonts.Register(path) adiciona um arquivo de fonte para devanágari, tailandês, chinês e outras escritas; o servidor MCP os obtém de MATPLOTLIBNET_FONTS. A mesma passagem de modelagem produz a medição do texto, os contornos de glifos SVG e os pixels PNG.

Gráficos 3D — 12 tipos de série: Surface, Wireframe, Scatter3D, Stem3D, Bar3D, PlanarBar3D, Line3D, Trisurf3D (Delaunay), Contour3D (marching squares), Quiver3D (campo vetorial), Voxels (cubos com face culling), Text3D (anotações). O suporte 3D inclui um pipeline Projection3D completo, um pintor com algoritmo do pintor DepthQueue3D, sombreamento a partir de Vec3.FaceNormal mais os métodos de extensão Color.Shade()/Color.Modulate(), Svg3DRotationScript para rotação no lado do cliente com reordenação por profundidade, faces traseiras derivadas da câmera (CubeFaceSelection: os painéis, arestas do cubo, grades de parede e linhas de ticks seguem a câmera em qualquer azimute, tanto no servidor quanto durante um arrasto), um Pane3DConfig configurável (cores de piso/parede) e suporte a barra de cores 3D.

Streaming e tempo real — StreamingLineSeries, StreamingScatterSeries, StreamingSignalSeries e StreamingCandlestickSeries são respaldados por RingBuffer<T> e adicionam pontos com AppendPoint(x, y). Um RingBuffer<T> é uma sequência circular de capacidade fixa de qualquer tipo (64 M appends/s, e nunca aloca em append). StreamingFigure fornece re-renderização com throttling e eixos com auto-escala (SlidingWindow, StickyRight, AutoScale). 11 indicadores de streaming (SMA, EMA, RSI, Bollinger, MACD, OBV, ATR, Stochastic, WilliamsR, CCI, VWAP) se anexam automaticamente a dados de candlestick. Existem controles de streaming para WPF, Avalonia, Uno, MAUI, Blazor e ASP.NET Core. A biblioteca inclui um motor de diff SVG para economizar largura de banda e um adaptador Rx IObservable<T>.

Projeções geográficas — o pacote MatPlotLibNet.Geo tem 13 projeções de mapa (PlateCarree, Mercator, TransverseMercator, Robinson, Orthographic, LambertConformal, AlbersEqualArea, AzimuthalEquidistant, EqualEarth, Mollweide, Natural Earth, Sinusoidal, Stereographic), um parser GeoJSON, dados Natural Earth 110m embutidos e GeoPolygonSeries para litorais, fronteiras e coropletas. Uma escala de eixo symlog lida com dados que abrangem intervalos positivos e negativos.

SignalR bidirecional — gráficos interativos com autoridade no servidor e eventos de mutação (zoom, pan, reset, alternância de legenda) e eventos de notificação (seleção por pincel, hover, o ponto de dados clicado). Os eventos formam uma hierarquia de registros empilhados, se mesclam por conta própria, e o servidor envia a cada chamador sua própria resposta de hover.

Acessibilidade — figure.ToDataTables() fornece a cada gráfico uma tabela de dados ao lado da imagem (ToHtml(), ToMarkdown(), ToCsv()). Essa tabela é a alternativa textual que a WCAG 1.1.1 exige para uma imagem complexa, e um <svg role="img"> não consegue fornecê-la sozinho. A tabela é servida por MapChartTableEndpoint, por MplChart.ShowDataTable, pelo campo GraphQL chartDataTable e pela ferramenta MCP chart_data_table, que a retorna como markdown para leitura e como valores estruturados para computação. A biblioteca também tem papéis e títulos ARIA, navegação por teclado, a paleta segura para daltonismo Okabe-Ito, as três sequências de cores acessíveis Petroff e um tema de alto contraste.

148 colormaps — viridis, plasma, turbo, coolwarm e mais 144 (74 mapas base, cada um com uma variante _r invertida registrada automaticamente). A biblioteca também tem numéricos SIMD no estilo NumPy (Vec, Mat, Linalg, Fft), temas com a aparência dos do matplotlib, integração com DataFrame com 58 indicadores técnicos, eixos quebrados e exportação SVG/PNG/PDF/GIF com qualidade de publicação.

---

Licença

MIT — livre para qualquer uso, open-source ou comercial, sem condições de copyleft.