Drawing of color surfaces is available on terminals supporting filled colored polygons with color mapping specified by palette. Currently supported terminals include
Screen terminals: OS/2 Presentation Manager X11 Linux VGA (vgagl) GGI Windows AquaTerm (Mac OS X) wxWidgets (wxt) Files: PostScript pslatex, pstex, epslatex gif, png, jpeg (x)fig tgif cgm pdf svg
Let us first describe how a map/surface is drawn. The input data come from an
evaluated function or from an splot data file. Each surface consists of a
sequence of separate scans (isolines). The pm3d algorithm fills the region
between two neighbouring points in one scan with another two points in the
next scan by a gray (or color) according to z-values (or according to an
additional 'color' column, see help for using (p. ![[*]](crossref.png)
)) of these 4 corners; by default
the 4 corner values are averaged, but this can be changed by the option
corners2color. In order to get a reasonable surface, the neighbouring scans
should not cross and the number of points in the neighbouring scans should not
differ too much; of course, the best plot is with scans having same number of
points. There are no other requirements (e.g. the data need not be gridded).
Another advantage is that the pm3d algorithm does not draw anything outside of
the input (measured or calculated) region.
Surface coloring works with the following input data:
1. splot of function or of data file with one or three data columns: The
gray/color scale is obtained by mapping the averaged (or corners2color)
z-coordinate of the four corners of the above-specified quadrangle into the
range [min_color_z,max_color_z] of zrange or cbrange providing a gray value
in the range [0:1]. This value can be used directly as the gray for gray maps.
The normalized gray value can be further mapped into a color -- see set palette (p. )
for the complete description.
2. splot of data file with two or four data columns: The gray/color value is obtained by using the last-column coordinate instead of the z-value, thus allowing the color and the z-coordinate be mutually independent. This can be used for 4d data drawing.
Other notes:
1. The term 'scan' referenced above is used more among physicists than the term 'iso_curve' referenced in gnuplot documentation and sources. You measure maps recorded one scan after another scan, that's why.
2. The 'gray' or 'color' scale is a linear mapping of a continuous variable
onto a smoothly varying palette of colors. The mapping is shown in a
rectangle next to the main plot. This documentation refers to this as a
"colorbox", and refers to the indexing variable as lying on the colorbox axis.
See set colorbox (p. ), set cbrange (p. ).
3. To use pm3d coloring to generate a two-dimensional plot rather than a 3D surface, use set view map or set pm3d map.
Syntax (the options can be given in any order):
set pm3d {
{ at <bst combination> }
{ interpolate <steps in scan>,<steps between scans> }
{ scansautomatic | scansforward | scansbackward | depthorder }
{ flush { begin | center | end } }
{ ftriangles | noftriangles }
{ clip1in | clip4in }
{ corners2color { mean|geomean|median|min|max|c1|c2|c3|c4 } }
{ hidden3d <linestyle> | nohidden3d }
{ implicit | explicit }
{ map }
}
show pm3d
unset pm3d
Color surface is drawn if data or function style is set to pm3d globally or via 'with' option, or if the option implicit is on -- then the pm3d surface is combined with the line surface mesh. See bottom of this section for mode details.
Color surface can be drawn at the base or top (then it is a gray/color planar map) or at z-coordinates of surface points (gray/color surface). This is defined by the at option with a string of up to 6 combinations of b, t and s. For instance, at b plots at bottom only, at st plots firstly surface and then top map, while at bstbst will never by seriously used.
Colored quadrangles are plotted one after another. When plotting surfaces (at s), the later quadrangles overlap (overdraw) the previous ones. (Gnuplot is not virtual reality tool to calculate intersections of filled polygon meshes.) You may try to switch between scansforward and scansbackward to force the first scan of the data to be plotted first or last. The default is scansautomatic where gnuplot makes a guess about scans order.
If two subsequent scans do not have same number of points, then it has to be decided whether to start taking points for quadrangles from the beginning of both scans (flush begin), from their ends (flush end) or to center them (flush center). Note, that flush (center4#4end) are incompatible with scansautomatic: if you specify flush center or flush end and scansautomatic is set, it is silently switched to scansforward.
If two subsequent scans do not have the same number of points, the option ftriangles specifies whether color triangles are drawn at the scan tail(s) where there are not enough points in either of the scan. This can be used to draw a smooth map boundary.
Clipping with respect to x, y coordinates of quadrangles can be done in two ways. clip1in: all 4 points of each quadrangle must be defined and at least 1 point of the quadrangle must lie in the x and y ranges. clip4in: all 4 points of each quadrangle must lie in the x and y ranges.
There is a single gray/color value associated to each drawn pm3d quadrangle (no smooth color change among vertices). The value is calculated from z-coordinates from the surrounding corners according to corners2color 5#5option6#6. The options 'mean' (default), 'geomean' and 'median' produce various kinds of surface color smoothing, while options 'min' and 'max' choose minimal or maximal value, respectively. This may not be desired for pixel images or for maps with sharp and intense peaks, in which case the options 'c1', 'c2', 'c3' or 'c4' can be used instead to assign the quadrangle color based on the z-coordinate of only one corner. Some experimentation may be needed to determine which corner corresponds to 'c1', as the orientation depends on the drawing direction. Because the pm3d algorithm does not extend the colored surface outside the range of the input data points, the 'c5#5j6#6' coloring options will result in pixels along two edges of the grid not contributing to the color of any quadrangle. For example, applying the pm3d algorithm to the 4x4 grid of data points in script demo/pm3d.dem (please have a look) produces only (4-1)x(4-1)=9 colored rectangles.
Another drawing algorithm, which would draw quadrangles around a given node by taking corners from averaged (x,y)-coordinates of its surrounding 4 nodes while using node's color, could be implemented in the future. This is already done for drawing images (2D grids) via image and rgbimage styles.
Notice that ranges of z-values and color-values for surfaces are adjustable
independently by set zrange, set cbrange, as well as set log for z or
cb. Maps can be adjusted by the cb-axis only; see also set view map (p. ) and
set colorbox (p. ).
The option hidden3d takes as the argument a linestyle which must be created
by set style line .... (The style need not to be present when setting pm3d,
but it must be present when plotting). If set, lines are drawn using the
specified line style, taking into account hidden line removal. This is by
far more efficient than using the command set hidden3d as it doesn't really
calculate hidden line removal, but just draws the filled polygons in the
correct order. So the recommended choice when using pm3d is
set pm3d at s hidden3d 100
set style line 100 lt 5 lw 0.5
unset hidden3d
unset surf
splot x*x+y*y
There used to be an option {transparent4#4solid} to this command. Now you get the same effect from set grid {front4#4layerdefault}, respectively.
The set pm3d map is an abbreviation for set pm3d at b; set view map; set style data pm3d; set style func pm3d;. It is used for backwards compatibility, when set view map was not available. Take care that you properly use zrange and cbrange for input data point filtering and color range scaling, respectively; and also set (no)surface seems to have a (side?) effect.
The option interpolate will interpolate grid points into a finer mesh, and color each quadrangle appropriately. For data files, this will smoothen the color surface, and enhance spikes in a color surface. For functions, interpolation makes little sense, except to trade off precision for memory. It would usually make more sense to use samples and isosamples when working with functions.
The coloring setup as well as the color box drawing are determined by set palette. There can be only one palette for the current plot. Drawing of several surfaces with different palettes can be achieved by multiplot with fixed origin and size; don't forget to use set palette maxcolors when your terminal is running out of available colors.
On gnuplot start-up, mode is explicit. For historical and thus compatibility reasons, commands set pm3d; (i.e. no options) and set pm3d at X ... (i.e. at is the first option) sets mode implicit. Further, set pm3d; sets up the other options to their default.
If the option implicit is on, all surface plots will be plotted additionally
to the default type, e.g.
splot 'fred.dat' with lines, 'lola.dat' with lines
If the option explicit is on (or implicit is off) only plots specified
by the with pm3d attribute are plotted with a pm3d surface, e.g.:
splot 'fred.dat' with lines, 'lola.dat' with pm3d
If you set the default data or function style to pm3d, e.g.:
set style data pm3d
Note that when plotting several plots, they are plotted in the order given on the command line. This can be of interest especially for filled surfaces which can overwrite and therefore hide part of earlier plots.
If with pm3d is specified in the splot command line, then it accepts the
'at' option. The following plots draw three color surfaces at different
altitudes:
set border 4095
set pm3d at s
splot 10*x with pm3d at b, x*x-y*y, x*x+y*y with pm3d at t
See also help for set palette (p. ), set cbrange (p. ), set colorbox (p. ), x11 pm3d (p. )
and definitely the demo file demo/pm3d.dem.