Splot

splot is the command for drawing 3D plots (well, actually projections on a 2D surface, but you knew that). It is the 3D equivalent of the plot command. splot provides only a single x, y, and z axis; there is no equivalent to the x2 and y2 secondary axes provided by plot.

See the plot command for many options available in both 2D and 3D plots.

Syntax:

splot {<ranges>}
      {<iteration>}
      <function> | {{<file name> | <datablock name>} {datafile-modifiers}}
                 | keyentry
      {<title-spec>} {with <style>}
      {, {definitions{,}} <function> ...}

The splot command operates on a data generated by a function, read from a data file, or stored previously in a named data block. Data file names are usually provided as a quoted string. 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 xyplane. The orientation of a splot projection is controlled by set view. See set view and set xyplane for more information.

The syntax for setting ranges on the splot command is the same as for plot. In non-parametric mode, ranges must be given in the order

splot [<xrange>][<yrange>][<zrange>] ...

In parametric mode, the order is

splot [<urange>][<vrange>][<xrange>][<yrange>][<zrange>] ...

The title option is the same as in plot. The operation of with is also the same as in plot except that not all 2D plotting styles are available.

The datafile options have more differences.

As an alternative to surfaces drawn using parametric or function mode, the pseudo-file '++' can be used to generate samples on a grid in the xy plane.

See also show plot, set view map, and sampling.

Data-file

Splot, like plot, can display from a file.

Syntax:

splot '<file_name>' {binary <binary list>}
                    {{nonuniform} matrix}
                    {index <index list>}
                    {every <every list>}
                    {using <using list>}

The special filenames "" and "-" are permitted, as in plot. See special-filenames.

In brief, binary and matrix indicate that 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 option smooth is not available for splot, but cntrparam and dgrid3d provide limited smoothing capabilities.

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 block number will be used for y, and the index of the data point in the block will be used for x. If two or four values are provided, gnuplot uses the last value for calculating the color in pm3d plots. 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 blocks of data in a splot datafile; splot treats blocks as the equivalent of function y-isolines. No line will join points separated by a blank record. If all blocks contain the same number of points, gnuplot will draw cross-isolines between points in the blocks, 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.

Matrix

Gnuplot can interpret matrix data input in two different ways.

The first of these assumes a uniform grid of x and y coordinates and assigns each value in the input matrix to one element M[i,j] of this uniform grid. The assigned x coordinates are the integers [0:NCOLS-1]. The assigned y coordinates are the integers [0:NROWS-1]. This is the default for text data input, but not for binary input. See matrix uniform for examples and additional keywords.

The second interpretation assumes a non-uniform grid with explicit x and y coordinates. The first row of input data contains the y coordinates; the first column of input data contains the x coordinates. For binary input data, the first element of the first row must contain the number of columns. This is the default for binary matrix input, but requires an additional keyword nonuniform for text input data. See matrix nonuniform for examples.

Uniform

Example commands for plotting uniform matrix data:

splot 'file' matrix using 1:2:3          # text input
splot 'file' binary general using 1:2:3  # binary input

In a uniform grid matrix 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.

For text input, if the first row contains column labels rather than data, use the additional keyword columnheaders. Similarly if the first field in each row contains a label rather than data, use the additional keyword rowheaders. Here is an example that uses both:

$DATA << EOD
xxx A   B   C   D
aa  z11 z12 z13 z14
bb  z21 z22 z23 z24
cc  z31 z32 z33 z34
EOD
plot $DATA matrix columnheaders rowheaders with image

For text input, a blank line or comment line ends the matrix, and starts a new surface mesh. You can select among the meshes inside a file by the index option to the splot command, as usual.

Nonuniform

The first row of input data contains the y coordinates. The first column of input data contains the x coordinates. For binary input data, the first field of the first row must contain the number of columns. (This number is ignored for text input).

Example commands for plotting non-uniform matrix data:

splot 'file' nonuniform matrix using 1:2:3  # text input
splot 'file' binary matrix using 1:2:3      # binary input

Thus the data organization for non-uniform matrix input is

<N+1>  <x0>   <x1>   <x2>  ...  <xN>
 <y0> <z0,0> <z0,1> <z0,2> ... <z0,N>
 <y1> <z1,0> <z1,1> <z1,2> ... <z1,N>
  :      :      :      :   ...    :

which is then 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.

Every

The every keyword has special meaning when used with matrix data. Rather than applying to blocks of single points, it applies to rows and column values. Note that matrix rows and columns are indexed starting from 0, so the row with index N is the (N+1)th row. Syntax:

plot 'file' every {<column_incr>}
                    {:{<row_incr>}
                      {:{<start_column>}
                        {:{<start_row>}
                          {:{<end_column>}
                            {:<end_row>}}}}}

Examples:

plot 'file' matrix every :::N::N   # plot all values in row with index N
plot 'file' matrix every ::3::7    # plot columns 3 to 7 for all rows
plot 'file' matrix every ::3:0:7:4 # submatrix bounded by [3,0] and [7,4]

Examples

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.

Usage in plot:

plot `a.dat` matrix
plot `a.dat` matrix using 1:3
plot 'a.gpbin' {matrix} binary using 1:3

will plot rows of the matrix, while using 2:3 will plot matrix columns, and using 1:2 the point coordinates (rather useless). Applying the every option you can specify explicit rows and columns.

Example – rescale axes of a matrix in a text file:

splot `a.dat` matrix using (1+$1):(1+$2*10):3

Example – plot the 3rd row of a matrix in a text file:

plot 'a.dat' matrix using 1:3 every 1:999:1:2

(rows are enumerated from 0, thus 2 instead of 3).

Gnuplot can read matrix binary files by use of the option binary appearing without keyword qualifications unique to general binary, i.e., array, record, format, or filetype. Other general binary keywords for translation should also apply to matrix binary. (See binary general for more details.)

Example datafile

A simple example of plotting a 3D 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 (blocks) 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 block, 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 block. 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.

Grid data

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 block, then "isolines" will connect the points in a block, and "cross-isolines" will connect the corresponding points in each block 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 style function 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 surfaces

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 cntrparam). 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.