plotpress 0.23.2__tar.gz → 0.25.0__tar.gz

{plotpress-0.23.2 → plotpress-0.25.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: plotpress
-Version: 0.23.2
-Summary: A fast, figure-centric, SVG-first plotting library with a matplotlib-like API and no global state.
+Version: 0.25.0
+Summary: A fast, figure-centric plotting library with a matplotlib-like API, no global state, and one figure exportable to SVG, PNG, PDF, interactive HTML, or Vega/Vega-Lite.
 Author: plotpress contributors
 License: MIT
 Project-URL: Homepage, https://github.com/jrvannucci/plotpress
@@ -20,10 +20,17 @@ Requires-Dist: pywebview>=4.0; extra == "gui"
 Provides-Extra: qt
 Requires-Dist: PyQt6>=6.4; extra == "qt"
 Requires-Dist: PyQt6-WebEngine>=6.4; extra == "qt"
-Provides-Extra: xarray
-Requires-Dist: xarray>=2023.1; extra == "xarray"
 Provides-Extra: jupyter
 Requires-Dist: ipython>=7; extra == "jupyter"
+Provides-Extra: viewers
+Requires-Dist: plotpress[gui]; extra == "viewers"
+Requires-Dist: plotpress[qt]; extra == "viewers"
+Requires-Dist: plotpress[jupyter]; extra == "viewers"
+Provides-Extra: xarray
+Requires-Dist: xarray>=2023.1; extra == "xarray"
+Provides-Extra: full
+Requires-Dist: plotpress[viewers]; extra == "full"
+Requires-Dist: plotpress[xarray]; extra == "full"
 Provides-Extra: dev
 Requires-Dist: pytest>=7; extra == "dev"
 Provides-Extra: browser
@@ -42,14 +49,24 @@ Requires-Dist: polars>=1.0; extra == "docs"
 Requires-Dist: adaptive>=1.0; extra == "docs"
 Requires-Dist: joblib>=1.3; extra == "docs"
 Requires-Dist: xarray>=2023.1; extra == "docs"
+Provides-Extra: contrib
+Requires-Dist: plotpress[dev]; extra == "contrib"
+Requires-Dist: plotpress[browser]; extra == "contrib"
+Requires-Dist: plotpress[bench]; extra == "contrib"
+Requires-Dist: plotpress[docs]; extra == "contrib"
 Dynamic: license-file
 
 # plotpress
 
-A **lightweight, dependency-light** plotting library that renders **SVG and
-self-contained interactive HTML** through a **matplotlib-shaped** API — with
-**no global state** and **no compiled extension**, so it installs everywhere
-`pip` runs.
+**Scientific plots you can explore, share, and reuse.**
+
+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`.
 
 ```python
 import plotpress
@@ -67,6 +84,187 @@ fig.save("out.html", interactive=True)    # interactive toolbar: zoom / pick / a
 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](https://jrvannucci.github.io/plotpress/auto_applications/index.html),
+embedded exactly this way) and it's fully live.
+
+**Pan / zoom**, working the same over every axes, not just the one under the cursor:
+
+![Wheel-zoom toward the cursor on one panel, then panning across to the next](https://raw.githubusercontent.com/jrvannucci/plotpress/main/assets/readme_zoom_pan.gif)
+
+**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:
+
+![Picking a point on a line panel and a mesh panel, then extracting both as CSV](https://raw.githubusercontent.com/jrvannucci/plotpress/main/assets/readme_point_picking.gif)
+
+**Annotation**, a free-form note whose label box drags independently of the
+point it's pinned to:
+
+![Dropping an annotation on a bar chart and dragging its label away from the point it's pinned to](https://raw.githubusercontent.com/jrvannucci/plotpress/main/assets/readme_annotation.gif)
+
+**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/examples/grouping/plot_13_full_scale_demo.py`](https://jrvannucci.github.io/plotpress/auto_examples/grouping/plot_13_full_scale_demo.html) —
+500 `pcolormesh` panels, 250 groups, each with its own colorbar):
+
+![Zooming from a 500-panel figure into a handful of panels, panning, picking a value, removing and re-picking it, dragging its label, panning to a distant group, annotating, then Home](https://raw.githubusercontent.com/jrvannucci/plotpress/main/assets/readme_scale_demo.gif)
+
+## 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](https://jrvannucci.github.io/plotpress/user_guide/architecture.html)
+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](https://jrvannucci.github.io/plotpress/usage.html#reading-html-data)
+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](https://jrvannucci.github.io/plotpress/auto_examples/data_roundtrip/index.html)
+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](#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
@@ -74,13 +272,15 @@ 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](#supported-plot-types)
 below). It aims at a narrower, underserved spot: plotting where matplotlib's
-install footprint or global state gets in the way.
+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 servers, minimal
-  containers, Pyodide/WASM, or CI — where a pure-Python + NumPy install with no
-  build toolchain and no per-platform wheels matters.
+- **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
@@ -98,38 +298,24 @@ with one figure per method, and
 grouped by field, each explaining the axis, scale and colour choices the data
 forces. Every application figure is embedded live, with the interactive toolbar.
 
-## 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.
-
 ## Install
 
 ```bash
 pip install plotpress            # SVG + interactive HTML + PNG/PDF export
-pip install plotpress[gui]       # + native pop-up window (fig.show(), pywebview)
-pip install plotpress[qt]        # + embed in a PyQt/PySide app (fig.show_qt())
-pip install plotpress[dev]       # + pytest (contributors)
-pip install plotpress[bench]     # + matplotlib (benchmark comparison)
+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). Only the native ``fig.show()`` window needs the ``[gui]`` extra,
-since it pulls a desktop webview stack; without it, ``fig.show()`` falls back to
-the browser.
+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](https://jrvannucci.github.io/plotpress/installation.html)
+for the full extras reference.
 
 ## Output surfaces (one scene, many targets)
 
@@ -180,11 +366,12 @@ grouped into Axes, Point Picking, Annotate, and File menus:
 - **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)` accept `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.
+`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

{plotpress-0.23.2 → plotpress-0.25.0}/README.md

@@ -1,9 +1,14 @@
 # plotpress
 
-A **lightweight, dependency-light** plotting library that renders **SVG and
-self-contained interactive HTML** through a **matplotlib-shaped** API — with
-**no global state** and **no compiled extension**, so it installs everywhere
-`pip` runs.
+**Scientific plots you can explore, share, and reuse.**
+
+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`.
 
 ```python
 import plotpress
@@ -21,6 +26,187 @@ fig.save("out.html", interactive=True)    # interactive toolbar: zoom / pick / a
 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](https://jrvannucci.github.io/plotpress/auto_applications/index.html),
+embedded exactly this way) and it's fully live.
+
+**Pan / zoom**, working the same over every axes, not just the one under the cursor:
+
+![Wheel-zoom toward the cursor on one panel, then panning across to the next](https://raw.githubusercontent.com/jrvannucci/plotpress/main/assets/readme_zoom_pan.gif)
+
+**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:
+
+![Picking a point on a line panel and a mesh panel, then extracting both as CSV](https://raw.githubusercontent.com/jrvannucci/plotpress/main/assets/readme_point_picking.gif)
+
+**Annotation**, a free-form note whose label box drags independently of the
+point it's pinned to:
+
+![Dropping an annotation on a bar chart and dragging its label away from the point it's pinned to](https://raw.githubusercontent.com/jrvannucci/plotpress/main/assets/readme_annotation.gif)
+
+**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/examples/grouping/plot_13_full_scale_demo.py`](https://jrvannucci.github.io/plotpress/auto_examples/grouping/plot_13_full_scale_demo.html) —
+500 `pcolormesh` panels, 250 groups, each with its own colorbar):
+
+![Zooming from a 500-panel figure into a handful of panels, panning, picking a value, removing and re-picking it, dragging its label, panning to a distant group, annotating, then Home](https://raw.githubusercontent.com/jrvannucci/plotpress/main/assets/readme_scale_demo.gif)
+
+## 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](https://jrvannucci.github.io/plotpress/user_guide/architecture.html)
+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](https://jrvannucci.github.io/plotpress/usage.html#reading-html-data)
+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](https://jrvannucci.github.io/plotpress/auto_examples/data_roundtrip/index.html)
+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](#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
@@ -28,13 +214,15 @@ 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](#supported-plot-types)
 below). It aims at a narrower, underserved spot: plotting where matplotlib's
-install footprint or global state gets in the way.
+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 servers, minimal
-  containers, Pyodide/WASM, or CI — where a pure-Python + NumPy install with no
-  build toolchain and no per-platform wheels matters.
+- **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
@@ -52,38 +240,24 @@ with one figure per method, and
 grouped by field, each explaining the axis, scale and colour choices the data
 forces. Every application figure is embedded live, with the interactive toolbar.
 
-## 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.
-
 ## Install
 
 ```bash
 pip install plotpress            # SVG + interactive HTML + PNG/PDF export
-pip install plotpress[gui]       # + native pop-up window (fig.show(), pywebview)
-pip install plotpress[qt]        # + embed in a PyQt/PySide app (fig.show_qt())
-pip install plotpress[dev]       # + pytest (contributors)
-pip install plotpress[bench]     # + matplotlib (benchmark comparison)
+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). Only the native ``fig.show()`` window needs the ``[gui]`` extra,
-since it pulls a desktop webview stack; without it, ``fig.show()`` falls back to
-the browser.
+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](https://jrvannucci.github.io/plotpress/installation.html)
+for the full extras reference.
 
 ## Output surfaces (one scene, many targets)
 
@@ -134,11 +308,12 @@ grouped into Axes, Point Picking, Annotate, and File menus:
 - **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)` accept `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.
+`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

{plotpress-0.23.2 → plotpress-0.25.0}/plotpress/__init__.py

@@ -10,8 +10,10 @@ Distinct from matplotlib in three ways:
    ``scatter``, ``pcolormesh``, ``set_xlabel``, ``legend`` mirror matplotlib so
    existing code is easy to port. ``plotpress.subplots(...)`` returns
    ``(fig, axes)`` just like ``plt.subplots(...)`` -- minus the globals.
-3. **SVG-first + fast.** Output is vector SVG (with embedded raster only for
-   mesh/image layers), optionally interactive. The hot paths are vectorized in
+3. **SVG-first, fast, and multi-format.** Output is vector SVG (with embedded
+   raster only for mesh/image layers) -- and from that same figure, also PNG,
+   PDF, self-contained interactive HTML (a full pan/zoom/pick/annotate
+   toolbar), or a Vega/Vega-Lite JSON spec. The hot paths are vectorized in
    NumPy and huge lines are decimated, so it is fast in **pure Python** -- no
    compiled extension, installs everywhere pip does.