[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

36. splot

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.

36.1 data-file  
36.2 grid_data  
36.3 splot_overview  

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

36.1 data-file

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.

36.1.1 binary  
36.1.2 example datafile  
36.1.3 matrix  

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

36.1.1 binary

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

36.1.2 example datafile

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

36.1.3 matrix

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

36.2 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 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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

36.3 splot_overview

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.

[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated by root l2-hrz on May, 9 2001 using texi2html