plotpress

Plot once. Share anywhere. Explore everywhere.

A fast, dependency-light plotting library for scientific computing, with a matplotlib-shaped API and no compiled extension — install it anywhere Python does, from notebooks to CI pipelines to offline environments. It renders one figure to SVG, PNG, PDF, Vega/Vega-Lite, and self-contained interactive HTML — the HTML carrying a full pan/zoom, point-picking, and annotation toolbar. No global state, either — a Figure owns its own axes and its own Style.

📖 Documentation  ·  User guide  ·  API reference  ·  Example gallery  ·  Real applications

import plotpress
import numpy as np

fig, ax = plotpress.subplots()
x = np.linspace(0, 4 * np.pi, 400)
ax.plot(x, np.sin(x), label="sin")
ax.plot(x, np.cos(x), label="cos", linestyle="--")
ax.set_xlabel("x"); ax.set_ylabel("y"); ax.legend()

fig.save("out.svg")                       # static vector SVG
fig.save("out.png"); fig.save("out.pdf")  # raster + vector export
fig.save("out.html", interactive=True)    # interactive toolbar: zoom / pick / annotate
fig.show()                                # native pop-up window

out.html above is a real, self-contained page — no server, no external JS — with a toolbar over every axes in the figure at once. Self-contained means genuinely shareable: the plotted data and the toolbar's own JS are both inlined into that one file, so anyone can open and interact with it with nothing installed on their end — no Python, no plotpress, no internet connection, just a browser. Email it, drop it in a chat, put it on a USB stick — it still works. Send someone a file, not a service they have to install. PyPI/GitHub READMEs can't run the page's own script, so the four GIFs below stand in for it; open one yourself (or click through to the real-applications gallery, embedded exactly this way) and it's fully live.

Pan / zoom, working the same over every axes, not just the one under the cursor:

Point picking, reading a value off any axes — a mesh's z, not just a line's x/y — then extracting every picked point as CSV/JSON:

Annotation, a free-form note whose label box drags independently of the point it's pinned to:

At scale, every gesture above still works the same way on a figure with hundreds of axes — zoom from the full grid into a handful of panels, pan, pick a value, remove it, pick again and drag its label, pan to a distant group, annotate, then back Home (the figure is docs/figure_layout/grouping/plot_13_full_scale_demo.py — 500 pcolormesh panels, 250 groups, each with its own colorbar):

One figure. Many destinations.

The same Figure built once from the matplotlib-shaped API renders to every format below — no separate figure per output, no plugin to install:

                                    one Figure object
                                            |
    +---------------+---------------+-------+-------+---------------+---------------+
    ▼               ▼               ▼               ▼               ▼               ▼
  .svg            .png            .pdf            .html           Vega          Vega-Lite
(vector,        (raster,        (vector,        (SVG + JS       (v5 JSON,      (v5 JSON, a
the core         Pillow)        svglib +       inlined --      real pixel-   stricter, more
 format)                       reportlab)       no server     space marks)     declarative
                                               round trip)                      grammar)

fig.save(path, ...) dispatches on the file extension for the first four; fig.to_vega() / fig.to_vega_lite() return a JSON specification as a plain dict for a separate Vega/Vega-Lite runtime to render — a bridge from scientific Python to web-native visualization, for handing a figure to an existing Vega-based dashboard or notebook without rebuilding the plot from scratch. See the architecture docs for exactly how much of the rendering pipeline each of these six actually shares, and where a format gets its own dedicated path instead.

Reading a figure back out of HTML

A plot doesn't have to be a dead image. The interactive HTML above isn't a one-way trip: it embeds the plotted data and the figure's own layout as JSON alongside the SVG, so a later process — with none of the Python objects that built it still around — can read a figure back out and rebuild it. The figure becomes a portable representation of the data it displays, not just a picture of it:

a saved .html (Figure.save(path, interactive=True))
      embeds <script id="plotpress-pick"> and
         id="plotpress-layout"> per figure
                         |
                         ▼
             plotpress.load_data(path)
         parses that embedded JSON back out
                          |
           +--------------+--------------+
           ▼                             ▼
       "layout"                       "axes"
   (grid shape, each            (recovered series/
axes' own decorations,        mesh/pie data per axes,
  groups, sup-title)              keyed by title)

           |
           ▼
       plotpress.subplots_from_layout(layout)
       rebuilds the grid and every axes' own
     decorations -- not the plotted data itself
                         |
                         ▼
     a new, already-labeled Figure -- ready for
     the caller to replot the recovered "axes"
                   data back into

A freeform Figure.add_axes() rect, an inset, or a colorbar axes has no grid cell to rebuild from — its index is listed in layout["omitted_axes"] instead of silently vanishing. See the full API and worked examples for the round trip end to end.

For the common case of a uniform grid — every axes its own single pcolormesh or line series, all the same shape — plotpress.load_data_xarray() skips the title-keyed dict above entirely and reads the same file straight into one xarray.Dataset indexed by row/column instead, with the recovered layout still available under ds.attrs["layout"] for plotpress.subplots_from_layout(). See the data round-trip example for both paths worked through end to end.

What makes it different

1. No pyplot, no globals. There is no "current figure/axes" and no global rcParams. A Figure owns its axes and its own Style; two figures never share mutable state. plotpress.subplots() returns (fig, axes) just like plt.subplots() — but touches no global state.
2. matplotlib-shaped API so moving code either direction is mostly mechanical: Figure/Axes, plot, scatter, pcolormesh, set_xlabel/ylabel/title, set_xlim/ylim, grid, legend, colorbar. It is shaped, not drop-in — there's no pyplot state machine and not every matplotlib keyword is present; treat the gallery as the compatibility surface.
3. SVG-first + built for speed. Output is vector SVG; only mesh/image layers are rasterized (as a single embedded <image>, not thousands of rects). Each series is one <path>. It's pure Python + NumPy — vectorized coordinate formatting, min/max-decimated huge lines — with no compiled extension, so it installs everywhere pip does.

Scientific visualization, end to end

plotpress is designed around the way scientific figures actually get used:

Explore ──► Analyze ──► Visualize ──► Share ──► Publish ──► Archive ──► Reuse
   ▲                                                                       │
   └───────────────────────────────────────────────────────────────────────┘

• Explore — interact with a measurement, simulation, image, or spectrum while building an experiment or analysis (pan/zoom, point-picking).
• Analyze — the same figure workflow for signal processing, statistics, and multidimensional data.
• Visualize — build and style the figure: plot, arrange subplots, apply colormaps and normalization.
• Share — hand an interactive HTML figure to a collaborator — no server, nothing to install on their end.
• Publish — export a publication figure as SVG/PNG/PDF, or publish a self-contained HTML figure that carries its own data.
• Archive — keep the figure and its plotted data together in one portable file.
• Reuse — load the figure back with plotpress.load_data(), recover the data, and analyze or replot it — the cycle starts again from Explore.

Made for real scientific workloads

plotpress isn't just a handful of basic plotting primitives — it covers the kinds of figures scientists actually build. See Supported plot types below for the full method list; the categories:

• Signal processing — power spectral density, cross-spectral density, coherence, spectrograms, autocorrelation, cross-correlation, and magnitude/angle/phase spectra (pure-NumPy Welch estimators).
• 2-D and gridded data — images, meshes (including curvilinear grids), contours, vector fields, and logarithmic/power/symlog normalization for large scientific fields.
• Statistical visualization — histograms, 2-D histograms, box plots, violin plots, ECDFs, KDEs, event rasters, error bars, and hexbins.
• Complex figures — subplot grids, shared axes, colorbars (including one shared across several axes), secondary axes, inset axes, grouped panels, figure-level titles/labels, and mixed layouts.
• Animation — animated lines and meshes with frame sliders, exportable as self-contained looping GIFs.
• Large figures — built to keep object and output-node counts under control, so a very large multi-panel figure stays practical; see the "At scale" GIF above (500 pcolormesh panels, 250 groups, each with its own colorbar).

What it is for

plotpress is not a matplotlib replacement, and it does not try to match matplotlib's twenty years of breadth (no geographic projections or triangulated grids, one font-metric family, no 3-D, and its polar axes project onto the 2-D core rather than a dedicated pipeline — see Supported plot types below). It aims at a narrower, underserved spot: plotting where matplotlib's install footprint or global state gets in the way — scientific software doesn't always run on a developer laptop.

Reach for plotpress when you want to:

• Ship plots from a constrained runtime — locked-down networks, offline systems, minimal containers, Pyodide/WASM, CI, or shared computing environments — where a pure-Python + NumPy install with no build toolchain and no per-platform wheels matters.
• Embed in web apps or notebooks as SVG or self-contained interactive HTML whose JS makes no external requests (works under strict CSPs like Jupyter).
• Write library or server code that should never touch a global "current figure" or a process-wide rcParams.

Reach for matplotlib (or seaborn, Plotly) when you need publication-grade typography across arbitrary fonts, the full plot-type gallery, 3-D, or the deep ecosystem that pandas, seaborn and scikit-learn plot into.

Two galleries in the docs, on separate pages: a plot-type reference with one figure per method, and real applications — a hundred-odd worked figures built from the data real measurements produce, grouped by field, each explaining the axis, scale and colour choices the data forces. Every application figure is embedded live, with the interactive toolbar.

Install

pip install plotpress            # SVG + interactive HTML + PNG/PDF export
pip install plotpress[full]      # + every real end-user feature: viewers (gui, qt, jupyter) + xarray
pip install plotpress[contrib]   # + everything a contributor needs (dev, browser, bench, docs)

The standard install covers all file output -- SVG, interactive HTML, PNG and vector PDF -- with pure-wheel dependencies that install everywhere (servers, CI, notebooks). [full] is likely what you want if you're reaching for more than that at all; each of its pieces ([gui], [qt], [jupyter], [xarray], or all three viewers via [viewers]) also installs on its own, or combined in one command (pip install plotpress[gui,xarray]), for anyone who wants less than the full bundle -- [gui], for instance, pulls a desktop webview stack for the native fig.show() window that a [qt]-only or [jupyter]-only install has no reason to carry. See Installation for the full extras reference.

Output surfaces (one scene, many targets)

Interactive figures

Interactive HTML and pop-up output carry a self-contained vanilla-JS toolbar (no external requests, so it works under strict CSPs like Jupyter and sandboxed webviews). Nothing is active until you pick a tool:

Pan/Zoom and Home sit standalone on the toolbar's left; everything else is grouped into Axes, Point Picking, Annotate, and File menus:

• Pan/Zoom — plain-wheel whole-figure zoom/pan, for wherever holding Ctrl (Axis Zoom's whole-figure gesture, below) is awkward. Home restores its magnification back to natural size.
• Axis Span — drag to pan a single plot's data window (log-aware).
• Axis Zoom — rubber-band box to zoom one axes in data space (ticks recompute, markers keep a constant size); Ctrl+wheel (or a trackpad pinch) zooms the whole figure instead, centered on the cursor. Reset All Axes restores every axes' own pan/zoom back to its original view; neither Reset button clears pins/annotations — double-click a single plot under Axis Span/Zoom to reset just that one.
• Point Picking — click to pin the nearest data point's value; arrow keys step along the series (nearest-neighbour for scatter, cell-by-cell for meshes/contours), reporting extra dims (z, c, …). Click a pin, or use Clear Points, to remove it. Its label box (connected to the marker by a leader arrow) is draggable while Point Picking is active. Hide Points toggles every pin's visibility without deleting them, and Extract copies/downloads them all as CSV/JSON, or hands them back to the kernel (fig.show(wait_for_extract=True)).
• Annotation — drop a user-written note anywhere on the figure, not locked to any datum; Clear Annotations removes only these, leaving Point Picking pins untouched (Escape clears both kinds at once, and deselects the active tool). Its box drags the same way, while Annotation is active. Hide Annotations toggles every note's visibility (plus any boxed callout the figure itself drew) without deleting them.
• Save/Save As — persist pan/zoom, every pin/annotation, and every toggle above to a new (or the same) self-contained HTML file.

fig.to_html()/fig.save(..., interactive=True) also accept extra_js — a raw JS string inlined as its own <script>, for adding a custom tool to the same toolbar menu — plus pick_precision (decimal places embedded per value) and pick_max_mesh_cells/pick_max_points (a hard cap on how much of each mesh/series is embedded for picking, per artist) to bound the interactive payload for mesh- or point-heavy figures.

Per axes: ax.set_pickable(False) excludes that axes from Point Picking (Axis Span/Zoom/Annotation still work everywhere), and ax.set_pick_context(**kwargs) attaches extra key/value context — e.g. a panel's spine color — that rides along on every record picked from it. Every picked record also always carries axes_title (falling back to a generated name when the axes has no title) plus xlabel/ylabel and zlabel (the title of any colorbar attached to that axes, shared or not), so a value pulled out of context still says what it means.

3-D data via ax.plot_frames(...) adds a slider (play/pause/step) over the extra dimension; multiple sliders can be linked by a shared index.

Supported plot types

plotpress covers the core of matplotlib's "Plot types" reference grid:

Signal processing (pure-NumPy Welch estimators): psd, csd, cohere, magnitude_spectrum, angle_spectrum, phase_spectrum, specgram, xcorr, acorr.

Polar (projection="polar"): plot, scatter, fill, with set_rmax/set_rlim/set_rticks/set_thetagrids and orientation control, projected onto the 2-D core — see the limitations docs for the caveats. No 3-D (see below).

Plus reference marks & fills — axhline/axvline, axhspan/axvspan, fill/fill_between/fill_betweenx, hlines/vlines — and axis control: log scales (set_xscale/set_yscale/loglog/semilogx), set_aspect("equal"), set_xlim/ylim, set_xticks/yticks, set_xticklabels/yticklabels, invert_xaxis/yaxis, margins, grid, set_axis_off, subplots(sharex=…, sharey=…) (plus post-hoc sharex()/sharey()), and twinx/twiny (overlaid axes with a second y/x axis), tick_params (per-axes, per-x/y-axis tick styling), and matplotlib "C0".."CN" cycle colors. Plus fig.tight_layout() (auto-margins so labels never overflow) and fig.subplots_adjust(...) / GridSpec row/column spans for direct margin control, ax.spines (per-side visible/color/linewidth), secondary_xaxis/secondary_yaxis (a mirrored, unit-converted second axis) and inset_axes (a nested axes), align_xlabels/align_ylabels, text (ax.text, ax.annotate with arrows), figure-level suptitle/supxlabel/supylabel, fig.colorbar(...) (single or shared across a list of axes), legend(loc=…, ncol=…, title=…), named colors ("red", "k", …), and 24 built-in colormaps (perceptually-uniform viridis/plasma/inferno/ magma/cividis; diverging coolwarm/RdBu/Spectral/PiYG/BrBG/ seismic; sequential Blues/Greens/Oranges/Reds/Purples/YlOrRd/ gray/hot/cool; cyclic twilight; rainbow jet/turbo; plus qualitative/categorical tab10/tab20/Set1/Dark2 for class labels with no natural ordering) + any _r reversed variant, with Normalize, LogNorm, PowerNorm, SymLogNorm, TwoSlopeNorm (a diverging colormap's midpoint pinned to a real center value), or BoundaryNorm (discrete bins) scaling, and plotpress.make_cmap()/register_cmap() for a custom one from any list of colors.

python examples/plot_types.py    # plot / scatter / bar / hist / pie / imshow / ...
python examples/plot_types_2.py  # boxplot / violin / quiver / contour / hist2d / ...
python examples/gallery.py       # line/scatter/pcolormesh/subplots

Not yet implemented (would need new primitives): streamplot, triangulation (tri*), and geographic / map projections. These are the main remaining plot-type gaps vs matplotlib's full gallery.

Testing

pip install plotpress[dev]         # pytest
python -m pytest -m "not perf"  # fast unit + output tests (~2s)
python -m pytest -m perf -s     # timing tests + speedup report (needs matplotlib)

The suite covers the no-global-state invariants, plotting/autoscale logic, transforms/tickers/colors, a lossless PNG round-trip, SVG/HTML well-formedness and structure, and performance (regression guards + a comparative claim vs matplotlib).

Point-picking tests (opt-in)

Point picking runs in JavaScript inside the interactive HTML, so it is tested end-to-end in a real browser: each case clicks the pixel where the renderer drew a known datum and asserts the marker reports that datum, across every pickable plot type (line, scatter, bar, stem, errorbar, quiver, eventplot, boxplot, violin, fill, pcolormesh, imshow, pie) and awkward axes (log, inverted, set_aspect, multi-subplot).

These need a browser, so they are deselected by default and skip cleanly when it is missing:

pip install plotpress[browser] && playwright install chromium
python -m pytest -m browser

Benchmarks

pip install plotpress[bench]        # matplotlib, for comparison
python benchmarks/benchmark.py  # plotpress vs matplotlib, plot build + SVG output

Representative run (best of 3, one machine — build and serialize to SVG, both using the object-oriented API):

Honest caveat: plotpress's win comes from avoiding matplotlib's per-Artist Python overhead (many axes) and from rasterizing meshes to one <image> instead of tens of thousands of vector cells (pcolormesh). The single huge polyline case used to be a loss (pure-Python float→string serialization of 100k points); it's now a win via min/max path decimation — a monotonic-x line is reduced to first/last/min/max per pixel column before serializing, which is visually lossless (spikes preserved), keeps the output vector, and needs no compiled backend. Coordinate formatting itself is already vectorized with numpy.char.

Roadmap

Done: pure-Python core with a self-contained object model; static SVG, interactive HTML, and native-window output; PNG + vector-PDF export; the full "Plot types" grid above; log scales and equal aspect; tight_layout; text / annotations and figure-level titles; per-axes data zoom / pan / box-zoom with live ticks, point-picking + extraction, in-browser annotation, and sliders for 3-D data.

Pure Python, and staying that way. plotpress is deliberately pure Python + NumPy with no compiled extension — it installs everywhere pip does, no build toolchain, no per-platform wheels. Speed comes from NumPy, not native code: coordinate formatting is vectorized, huge lines are min/max-decimated (the 100k-point line runs ~5.6× vs matplotlib), and curvilinear / Gouraud meshes scan-convert in NumPy. The "installs everywhere" promise is a first-class feature, not a trade-off.

Next:

• Finish unifying the SVG and raster renderers behind the shared primitive layer (pure Python) so features aren't implemented twice.
• More plot types: streamplot/barbs and triangulation (tri*).
• Deeper polar (polar bars, cross-collection depth sorting).
• Hover tooltips; decimation for huge scatter collections.

Architecture notes

plotpress/ layout:

Artists never render themselves — they just hold arrays. The geometry of each artist is computed once in primitives.py; svg.py and raster.py are thin emitters over that shared primitive vocabulary, so an artist is defined in one place, not per backend.

Fonts. A figure is laid out before anything draws its glyphs — SVG emits <text> and lets the viewer rasterize — so plotpress has to predict text width from bundled metric tables. That keeps layout identical on every machine with no font-file dependency. Bundled are the base-14 metric families — Helvetica, Times and Courier, each in regular / bold / italic / bold-italic — plus DejaVu Sans, which covers the metric-compatible clones too (Arial and Liberation Sans are Helvetica, Liberation Serif is Times, Liberation Mono is Courier). Families outside those groups — Verdana, Tahoma, Arial Black, Arial Narrow — have proprietary metrics, so they render but are measured as Helvetica and need hand-tuned figsize; Style(measure_installed_fonts=True) opts into measuring the real file on this machine instead, trading cross-machine reproducibility for fidelity. PNG export picks a matching face, falling back to Pillow's built-in font where the system has none.