splot is the command for drawing 3-d plots (well, actually projections on
a 2-d surface, but you knew that). It can create a plot from functions or
a data file in a manner very similar to the plot command.
See plot for features common to the plot command; only differences are
discussed in detail here. Note specifically that the binary and matrix
options (discussed under "datafile-modifiers") are not available for plot.
Syntax:
splot {<ranges>}
<function> | "<datafile>" {datafile-modifiers}}
{<title-spec>} {with <style>}
{, {definitions,} <function> ...}
where either a <function> or the name of a data file enclosed in quotes is supplied. The function can be a mathematical expression, or a triple of mathematical expressions in parametric mode.
By default splot draws the xy plane completely below the plotted data.
The offset between the lowest ztic and the xy plane can be changed by `set
ticslevel. The orientation of a splot` projection is controlled by
set view. See set view and set ticslevel for more information.
The syntax for setting ranges on the splot command is the same as for
plot. In non-parametric mode, the order in which ranges must be given is
xrange, yrange, and zrange. In parametric mode, the order is urange,
vrange, xrange, yrange, and zrange.
The title option is the same as in plot. The operation of with is also
the same as in plot, except that the plotting styles available to splot
are limited to lines, points, linespoints, dots, and impulses; the
error-bar capabilities of plot are not available for splot.
The datafile options have more differences.
As for plot, discrete data contained in a file can be displayed by
specifying the name of the data file, enclosed in quotes, on the splot
command line.
Syntax:
splot '<file_name>' {binary | matrix}
{index <index list>}
{every <every list>}
{using <using list>}
The special filenames "" and "-" are permitted, as in plot.
In brief, binary and matrix indicate that the the data are in a special
form, index selects which data sets in a multi-data-set file are to be
plotted, every specifies which datalines (subsets) within a single data
set are to be plotted, and using determines how the columns within a single
record are to be interpreted.
The options index and every behave the same way as with plot; using
does so also, except that the using list must provide three entries
instead of two.
The plot options thru and smooth are not available for splot, but
cntrparams and dgrid3d provide limited smoothing cabilities.
Data file organization is essentially the same as for plot, except that
each point is an (x,y,z) triple. If only a single value is provided, it
will be used for z, the datablock number will be used for y, and the index
of the data point in the datablock will be used for x. If two values are
provided, gnuplot gives you an error message. Three values are interpreted
as an (x,y,z) triple. Additional values are generally used as errors, which
can be used by fit.
Single blank records separate datablocks in a splot datafile; splot
treats datablocks as the equivalent of function y-isolines. No line will
join points separated by a blank record. If all datablocks contain the same
number of points, gnuplot will draw cross-isolines between datablocks,
connecting corresponding points. This is termed "grid data", and is required
for drawing a surface, for contouring (set contour) and hidden-line removal
(set hidden3d). See also splot grid data
It is no longer necessary to specify parametric mode for three-column
splots.
splot can read binary files written with a specific format (and on a
system with a compatible binary file representation.)
In previous versions, gnuplot dynamically detected binary data files. It
is now necessary to specify the keyword binary directly after the filename.
Single precision floats are stored in a binary file as follows:
<N+1> <y0> <y1> <y2> ... <yN>
<x0> <z0,0> <z0,1> <z0,2> ... <z0,N>
<x1> <z1,0> <z1,1> <z1,2> ... <z1,N>
: : : : ... :
which are converted into triplets:
<x0> <y0> <z0,0>
<x0> <y1> <z0,1>
<x0> <y2> <z0,2>
: : :
<x0> <yN> <z0,N>
<x1> <y0> <z1,0>
<x1> <y1> <z1,1>
: : :
These triplets are then converted into gnuplot iso-curves and then
gnuplot proceeds in the usual manner to do the rest of the plotting.
A collection of matrix and vector manipulation routines (in C) is provided
in binary.c. The routine to write binary data is
int fwrite_matrix(file,m,nrl,nrl,ncl,nch,row_title,column_title)
An example of using these routines is provided in the file bf_test.c, which
generates binary files for the demo file demo/binary.dem.
The index keyword is not supported, since the file format allows only one
surface per file. The every and using filters are supported. using
operates as if the data were read in the above triplet form.
A simple example of plotting a 3-d data file is
splot 'datafile.dat'
where the file "datafile.dat" might contain:
# The valley of the Gnu.
0 0 10
0 1 10
0 2 10
1 0 10
1 1 5
1 2 10
2 0 10
2 1 1
2 2 10
3 0 10
3 1 0
3 2 10
Note that "datafile.dat" defines a 4 by 3 grid ( 4 rows of 3 points each ). Rows (datablocks) are separated by blank records.
Note also that the x value is held constant within each dataline. If you instead keep y constant, and plot with hidden-line removal enabled, you will find that the surface is drawn 'inside-out'.
Actually for grid data it is not necessary to keep the x values constant
within a datablock, nor is it necessary to keep the same sequence of y
values. gnuplot requires only that the number of points be the same for
each datablock. However since the surface mesh, from which contours are
derived, connects sequentially corresponding points, the effect of an
irregular grid on a surface plot is unpredictable and should be examined
on a case-by-case basis.
The matrix flag indicates that the ASCII data are stored in matrix format.
The z-values are read in a row at a time, i. e.,
z11 z12 z13 z14 ...
z21 z22 z23 z24 ...
z31 z32 z33 z34 ...
and so forth. The row and column indices are used for the x- and y-values.
The 3D routines are designed for points in a grid format, with one sample,
datapoint, at each mesh intersection; the datapoints may originate from
either evaluating a function, see set isosamples, or reading a datafile,
see splot datafile. The term "isoline" is applied to the mesh lines for
both functions and data. Note that the mesh need not be rectangular in x
and y, as it may be parameterized in u and v, see set isosamples.
However, gnuplot does not require that format. In the case of functions,
'samples' need not be equal to 'isosamples', i.e., not every x-isoline
sample need intersect a y-isoline. In the case of data files, if there
are an equal number of scattered data points in each datablock, then
"isolines" will connect the points in a datablock, and "cross-isolines"
will connect the corresponding points in each datablock to generate a
"surface". In either case, contour and hidden3d modes may give different
plots than if the points were in the intended format. Scattered data can be
converted to a {different} grid format with set dgrid3d.
The contour code tests for z intensity along a line between a point on a
y-isoline and the corresponding point in the next y-isoline. Thus a splot
contour of a surface with samples on the x-isolines that do not coincide with
a y-isoline intersection will ignore such samples. Try:
set xrange [-pi/2:pi/2]; set yrange [-pi/2:pi/2]
set function style lp
set contour
set isosamples 10,10; set samples 10,10;
splot cos(x)*cos(y)
set samples 4,10; replot
set samples 10,4; replot
splot can display a surface as a collection of points, or by connecting
those points. As with plot, the points may be read from a data file or
result from evaluation of a function at specified intervals, see `set
isosamples`. The surface may be approximated by connecting the points
with straight line segments, see set surface, in which case the surface
can be made opaque with set hidden3d. The orientation from which the 3d
surface is viewed can be changed with set view.
Additionally, for points in a grid format, splot can interpolate points
having a common amplitude (see set contour) and can then connect those
new points to display contour lines, either directly with straight-line
segments or smoothed lines (see set cntrparams). Functions are already
evaluated in a grid format, determined by set isosamples and set samples,
while file data must either be in a grid format, as described in data-file,
or be used to generate a grid (see set dgrid3d).
Contour lines may be displayed either on the surface or projected onto the
base. The base projections of the contour lines may be written to a
file, and then read with plot, to take advantage of plot's additional
formatting capabilities.