Metadata-Version: 2.4
Name: zoomy-plotting
Version: 0.1.0
Summary: Plotting for Zoomy simulation outputs (HDF5 + VTK)
Author-email: Ingo Steldermann <steldermann@mbd.rwth-aachen.de>
License: GNU
Project-URL: Homepage, https://github.com/mbd-rwth/Zoomy
Project-URL: Source, https://github.com/mbd-rwth/Zoomy
Project-URL: Issues, https://github.com/mbd-rwth/Zoomy/issues
Keywords: simulation,visualization,plotting,mesh,HDF5,VTK
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: h5py
Requires-Dist: meshio
Requires-Dist: sympy
Provides-Extra: plotly
Requires-Dist: plotly; extra == "plotly"
Provides-Extra: pyvista
Requires-Dist: pyvista; extra == "pyvista"
Provides-Extra: testing
Requires-Dist: pytest; extra == "testing"
Requires-Dist: pytest-mpl; extra == "testing"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-mpl; extra == "dev"
Requires-Dist: ruff; extra == "dev"

# zoomy-plotting

Publication-ready plotting for Zoomy simulation outputs, with first-class
support for 1D/2D/3D meshes and very large timeline datasets.

## Why

- **Lazy**: an HDF5 file with hundreds of snapshots opens cheaply. Only the
  cells needed for the current plot are read from disk.
- **Class-based, one `store` per session**. Pass the store once to a
  `MatplotlibPlotter`; plot methods take only `(ax, time_step, field, ...)`.
- **Config-driven styling**. Every color, linewidth, colormap, and marker
  size lives in `zoomy_plotting.CONFIG`. No visual parameter is hardcoded
  inside the plot functions.
- **One API across dimensions**. `plot_1d` / `plot_2d` / `plot_3d` share
  the same signature modulo the 3D viewpoint.

## Quick start

```python
import zoomy_plotting as zp
import matplotlib.pyplot as plt

store = zp.read_hdf5("simulation.h5")          # reads metadata only
plotter = zp.MatplotlibPlotter(store)

with zp.apply_style():
    fig, ax = plt.subplots()
    plotter.plot_1d(ax, time_step=0, field=store.field.h)
    plt.show()

store.close()
```

## Field references

All three forms resolve to the same integer index:

```python
plotter.plot_2d(ax, time_step=0, field=store.field.h)   # attribute on Zstruct
plotter.plot_2d(ax, time_step=0, field="h")             # string lookup
plotter.plot_2d(ax, time_step=0, field=0)               # raw index
```

## Styling

Three ways to restyle:

```python
# 1. per-call kwarg override
plotter.plot_2d(ax, time_step=0, field="h", cmap="plasma")

# 2. mutate the singleton config for the rest of the session
zp.CONFIG.cmap = "plasma"
zp.CONFIG.mesh_edgecolor = "gray"

# 3. context manager that reverts on exit
with zp.apply_style(cmap="plasma", mesh_edgecolor="gray"):
    plotter.plot_2d(ax, time_step=0, field="h")
```

## Install

```bash
pip install -e .[testing]       # for tests
pip install -e .[plotly]        # optional plotly backend (future PR)
pip install -e .[pyvista]       # optional pyvista backend (future PR)
```
