3.24.52 pm3d

pm3d is an ‘splot‘ style for drawing palette-mapped 3d and 4d data as color/gray maps and surfaces. It uses a pm3d algorithm which allows plotting gridded as well as non-gridded data without preprocessing, even when the data scans do not have the same number of points.

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
    emf

Let us first describe how a map/surface is drawn. The input data come from an evaluated function or from an 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) 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 palette 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‘, cbrange.

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/points in scan, 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. On the other hand, the depthorder option completely reorders the quadrangles. The rendering is performed after a depth sorting, which allows to visualize even complicated surfaces; see depthorder for more details.

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 (center|end)‘ 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 <option>‘. 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 ’c<j>’ 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 zrange, cbrange, as well as ‘set log‘ for z or cb. Maps can be adjusted by the cb-axis only; see also ‘set view map‘ and ‘set colorbox‘.

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 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 {transparent|solid} to this command. Now you get the same effect from ‘set grid {front|layerdefault}‘, respectively.

The ‘set pm3d map‘ is an abbreviation for ‘set pm3d at b‘; ‘set view map‘; pm3d; 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 m,n‘ 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. For positive m and n, each quadrangle or triangle is interpolated m-times and n-times in the respective direction. For negative m and n, the interpolation frequency is chosen so that there will be at least |m| and |n| points drawn; you can consider this as a special gridding function. Zeros, i.e. ‘interpolation 0,0‘, will automatically choose an optimal number of interpolated surface points.

The coloring setup as well as the color box drawing are determined by 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

would give both plots (meshes) additionally to a pm3d surface. That’s what you are used to after ‘set pm3d;‘.

If the option ‘explicit‘ is on (or ‘implicit‘ is off) only plots specified by the pm3d attribute are plotted with a pm3d surface, e.g.:

      splot 'fred.dat' with lines, 'lola.dat' with pm3d

would plot ’fred.dat’ with lines (and only lines) and ’lola.dat’ with a pm3d surface.

If you set the default data or function style to pm3d, e.g.:

      set style data pm3d

then the options ‘implicit‘ and ‘explicit‘ have no effect.

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 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 palette, cbrange, ‘set colorbox‘, pm3d and definitely the demo file ‘demo/pm3d.dem‘.