ahay/src/plotting-with-vplot

When to use

Use this skill any time a task involves:

• Producing a .vpl file — Madagascar's portable vector/raster plot format.
• Calling sfgrey, sfgraph, sfwiggle, sfcontour, sfdots, or sfbargraph from an SConstruct or at the command line.
• Debugging a blank, mis-scaled, or mis-labeled plot.
• Composing multiple plots into an overlay, side-by-side panel, or animation.
• Writing axis labels that require subscripts, superscripts, or Greek letters.
• Controlling color schemes, clip levels, or scalebars.

This skill does not cover converting .vpl to PDF/PNG (use sfpen options or vppen), or 3D surface plots (sfgrey3, sfsurf).

Mental model

What vplot is

Vplot is Madagascar's internal plot language — a compact binary stream describing lines, rasters, text, and color tables. Every visualization program (sfgrey, sfgraph, etc.) reads an RSF file and writes a .vpl stream. The .vpl file can be:

• Displayed on screen with sfpen (wraps the xtpen or pspen driver).
• Composed with other .vpl files using vppen.
• Converted to PostScript with pspen.

Programs vs. the pipeline

Every vplot program is a standard Madagascar filter:

< data.rsf sfgrey color=j clip=1 title="My data" > out.vpl

At the command line, output goes to stdout. In SConstruct, SCons manages the filenames.

Plot vs. Result in SConstruct

Plot and Result are the two SConstruct functions that produce .vpl files.

Rules of thumb:

• Use Plot for any image you intend to overlay or combine.
• Use Result for any image that is a deliverable on its own.
• A Result with a composition string is both — it reads Plot-produced .vpl files and writes a final composed .vpl to Fig/.

How parameters reach the vplot program

In SConstruct, the second argument to Plot or Result is either:

1. A flow string — the vplot program call with its parameters:

``python Result('img', 'grey title="My plot" color=j clip=2') ``

1. A source list plus a composition keyword:

``python Result('combined', 'img1 img2', 'Overlay') ``

Parameters follow the same key=value syntax as any sf program. String values with spaces must be quoted.

Universal parameter inheritance

All vplot programs call sfstdplot internally (see sfdoc stdplot). This means axis labels, title, min/max, grid, screen size, and layout parameters are available to every vplot program, not just the one documented in its own sfdoc entry.

Core program catalog

Universal plot parameters

These parameters come from sfstdplot (run sfdoc stdplot) and are accepted by every vplot program.

Program-specific parameters

sfgrey — 2D raster/density plot

sfdoc sfgrey | source: plot/main/grey.c

Defaults: transp=y yreverse=y xreverse=n. With these defaults, axis 1 runs vertically (time, depth), axis 2 runs horizontally (trace, offset). This is the standard seismic display convention.

clip vs. pclip: pclip=99 (default) estimates clip from the 99th percentile. Set clip= explicitly for reproducible cross-panel display. gainpanel=a normalizes across all 3D frames; gainpanel=e per frame. For strictly positive data (envelopes, migration images) use allpos=y color=j.

sfgraph — 1D line plot

sfdoc sfgraph | source: plot/main/graph.c

Default: transp=n. Plots each column (n2 traces) as a curve, with axis 1 values on the vertical axis and axis 2 index on the horizontal.

Overlay alignment: Both plots must share axis ranges. With sfgrey transp=y (default), axis 1 is vertical and min1/max1 control vertical range. With sfgraph transp=y yreverse=y, the curve values map to the vertical axis via min2/max2. Always use wantaxis=n wanttitle=n pad=n on the overlay graph.

sfwiggle — seismic trace display

sfdoc sfwiggle | source: plot/main/wiggle.c

Draws each trace as an oscillating waveform. Positive excursions can be filled (polygon mode).

Note on clip: sfwiggle requires an explicit positive clip to work properly. Either set clip=<value> directly, or rely on pclip=98 (the default) which estimates the clip from the data percentile. Setting clip=0 with no pclip produces no display.

sfcontour — contour plot

sfdoc sfcontour | source: plot/main/contour.c

Draws iso-value lines on a 2D scalar field. Defaults: transp=y allpos=y.