Description

pymplot is a lightweight Python plotting package for generating high-quality figures from multi-dimensional scalar data. It provides a command-line interface (CLI) for rapid visualization without writing custom plot scripts, while supporting fine-grained control over every visual element.

The work is under LANL open source approval reference C20105.

Reference

Please refer to the paper draft for details.

Installation

Install from the repo root:

pip install -e .

This installs the pymplot Python package and registers all CLI tools (x_showmatrix, x_showcontour, etc.) as system commands. Dependencies (numpy, scipy, matplotlib, pyvista) are installed automatically.

Documentation

Run any command without arguments (e.g. x_showmatrix) to print the full argument reference.

Function API

In addition to the CLI, all tools are available as Python functions via src/api.py:

from pymplot import showmatrix, showcontour, showslice, showwiggle, showvolume, showgraph

Each function accepts a NumPy array as its first argument and the same keyword arguments as the CLI flags:

import numpy as np
from pymplot import showmatrix, showcontour, showslice

data2d = np.random.rand(80, 120).astype('float32')
data3d = np.random.rand(40, 50, 30).astype('float32')

showmatrix(data2d, colormap='jet', legend=True, outfile='matrix.pdf')
showcontour(data2d, overlay=True, outfile='contour.pdf')
showslice(data3d, slice1=20, slice2=25, slice3=15, outfile='slices.pdf')

Functions also accept an ax= argument for embedding into an existing matplotlib figure — enabling multi-panel layouts without any temporary files:

import matplotlib.pyplot as plt
from pymplot import showmatrix, showcontour, showwiggle, showvolume

fig, axes = plt.subplots(2, 2, figsize=(12, 9))
showmatrix(data2d, colormap='seismic', legend=True, ax=axes[0, 0])
showcontour(data2d, overlay=True,                  ax=axes[0, 1])
showwiggle(data2d[:, :30], fill=True,              ax=axes[1, 0])
showvolume(data3d,                                 ax=axes[1, 1])
plt.tight_layout()
plt.savefig('panel.pdf')

See example/test_api.py for a full worked example.

---

Main Features

2D Matrix / Image Plot — x_showmatrix

Displays a 2D array as a color image.

• Any matplotlib colormap plus custom colormaps (e.g. rainbow256, coldwarm)
• Multiple font families: Arial, Helvetica, Times, Courier, Consolas, IBM Plex
• Flexible tick labels — per-tick custom strings, multi-line, LaTeX math
• Colorbar with configurable position, tick spacing, log/linear scale
• Annotations: text, arrows, polygons, circles, all with full style control

2D Contour Plot — x_showcontour

Overlays contour lines (and optionally filled contours) on a scalar field.

• Auto or manually specified contour levels; log-scale contours
• Optional background image overlay
• Contour label placement with font and color control
• Irregular domain support via axis origin/spacing options

Wiggle Trace Plot — x_showwiggle

Seismic-style wiggle traces with optional filled amplitude shading.

• Multiple overlaid datasets with independent color and width
• Horizontal or vertical trace orientation
• Gaussian-interpolated background image option

1D Graph / Scatter Plot — x_showgraph

Line, scatter, and bubble plots for 1D or tabular data.

• Multiple datasets on one figure; selectable columns
• Log axis, axis closure, marker styles
• Arrows, text annotations, polygons
• Bubble size scaling by a third variable

3D Cavalier Projection — x_showvolume

Renders a 3D volume as a cavalier (oblique parallel) projection.

• Four octant orientations (--+, ---, -+-, -++)
• Interior slice planes exposed by cutting a corner out of the volume
• Configurable view angles, colormap, colorbar, all axis tick/label options
• 3D interactive mode (--render 3d): solid volume rendered with PyVista, corner clipped to expose interior, camera auto-oriented to face the cut

3D Volume Contour Plot — x_showvolcon

Cavalier projection with 3D contour surfaces on the slice planes.

• Filled or line contours; log-scale option
• Same octant and angle controls as x_showvolume

3D Orthogonal Slice Plot — x_showslice

Three orthogonal cross-sections displayed together.

• 2D panel layout or 3D perspective view (--render 3d)
• Configurable slice positions along each axis

3D Slice + Contour Overlay — x_showslicon

Combines x_showslice imagery with contour lines on the same slice planes.

---

Examples

All examples can be reproduced with example/test.rb.

2D matrix — Marmousi velocity model (multiple colormaps and fonts)

jet / Arial	gist_ncar / Consolas	bwr / Times
binary / Courier	viridis / Plex	rainbow256 / Helvetica

2D matrix — BP velocity model with annotations

2D matrix — flexible tick labels

Wiggle trace plots

Horizontal, two datasets

Vertical, filled

Vertical, image background

1D graph / scatter plots

Phase velocity diagram

Scatter / bubble with annotations

2D contour plots

Traveltime with image overlay

Traveltime on irregular topography

3D volume cavalier projection and contours

Cavalier projection

Volume contours (linear)

Volume contours (log)

3D volume PyVista render

3D orthogonal slice plots

Three orthogonal slices (3D view)

Slices with contour overlay

---

License

pymplot is distributed under the BSD license. See LICENSE for details.

Author

Kai Gao, kaigao@lanl.gov

Feedback, bug reports, and improvement ideas are welcome.

If you use this package in your research, please cite:

Kai Gao, Lianjie Huang, 2020, Pymplot: An open-source, lightweight plotting package based on Python and matplotlib, url: github.com/lanl/pymplot