Image

The image, rgbimage, and rgbalpha plotting styles all project a uniformly sampled grid of data values onto a plane in either 2D or 3D. The input data may be an actual bitmapped image, perhaps converted from a standard format such as PNG, or a simple array of numerical values.

This figure illustrates generation of a heat map from an array of scalar values. The current palette is used to map each value onto the color assigned to the corresponding pixel.

plot '-' matrix with image
5 4 3 1 0
2 2 0 0 1
0 0 0 1 0
0 1 2 4 3
e
e

Each pixel (data point) of the input 2D image will become a rectangle or parallelipiped in the plot. The coordinates of each data point will determine the center of the parallelipiped. That is, an M x N set of data will form an image with M x N pixels. This is different from the pm3d plotting style, where an M x N set of data will form a surface of (M-1) x (N-1) elements. The scan directions for a binary image data grid can be further controlled by additional keywords. See binary keywords flipx, keywords center, and keywords rotate.

Image data can be scaled to fill a particular rectangle within a 2D plot coordinate system by specifying the x and y extent of each pixel. See binary keywords dx and dy. To generate the figure at the right, the same input image was placed multiple times, each with a specified dx, dy, and origin. The input PNG image of a building is 50x128 pixels. The tall building was drawn by mapping this using dx=0.5 dy=1.5. The short building used a mapping dx=0.5 dy=0.35.

The image style handles input pixels containing a grayscale or color palette value. Thus 2D plots (plot command) require 3 columns of data (x,y,value), while 3D plots (splot command) require 4 columns of data (x,y,z,value).

The rgbimage style handles input pixels that are described by three separate values for the red, green, and blue components. Thus 5D data (x,y,r,g,b) is needed for plot and 6D data (x,y,z,r,g,b) for splot. The individual red, green, and blue components are assumed to lie in the range [0:255]. This matches the convention used in PNG and JPEG files (see binary filetype). However some data files use an alternative convention in which RGB components are floating point values in the range [0:1]. To use the rgbimage style with such data, the color component values must be rescaled to the range [0:255].

The rgbalpha style handles input pixels that contain alpha channel (transparency) information in addition to the red, green, and blue components. Thus 6D data (x,y,r,g,b,a) is needed for plot and 7D data (x,y,z,r,g,b,a) for splot. The r, g, b, and alpha components are assumed to lie in the range [0:255]. To plot data for which RGBA components are floating point values in the range [0:1] you must rescale the components to lie in the range [0:255].

Transparency

The rgbalpha plotting style assumes that each pixel of input data contains an alpha value in the range [0:255]. A pixel with alpha = 0 is purely transparent and does not alter the underlying contents of the plot. A pixel with alpha = 255 is purely opaque. All terminal types can handle these two extreme cases. A pixel with 0 < alpha < 255 is partially transparent. Terminal types that do not support partial transparency will round this value to 0 or 255.

Image pixels

Some terminals use device- or library-specific optimizations to render image data within a rectangular 2D area. This sometimes produces undesirable output, e.g. bad clipping or scaling, missing edges. The pixels keyword tells gnuplot to use generic code that renders the image pixel-by-pixel instead. This rendering mode is slower and may result in much larger output files, but should produce a consistent rendered view on all terminals. (The pixels options was called failsafe mode in previous gnuplot versions.) Example:

plot 'data' with image pixels