info gnuplot

3.14.2.2 binary general

General binary data in which format information is not necessarily part of the file can be read by giving further details about the file format at the command line. Although the syntax is slightly arcane to the casual user, general binary is particularly useful for application programs using gnuplot and sending large amounts of data.

Syntax:

      plot '<file_name>' {binary <binary list>} ...
      splot '<file_name>' {binary <binary list>} ...

General binary format is activated by keywords in <binary list> pertaining to information about file structure, i.e., ‘array‘, ‘record‘, ‘format‘ or ‘filetype‘. Otherwise, matrix binary format is assumed. (See ‘binary matrix‘ for more details.)

There are some standard file types that may be read for which details about the binary format may be extracted automatically. (Type ‘show datafile binary‘ at the command line for a list.) Otherwise, details must be specified at the command line or set in the defaults. Keywords are described below.

The keyword ‘filetype‘ in <binary list> controls the routine used to read the file, i.e., the format of the data. For a list of the supported file types, type ‘show datafile binary filetypes‘. If no file type is given, the rule is that traditional gnuplot binary is assumed for ‘splot‘ if the ‘binary‘ keyword stands alone. In all other circumstances, for ‘plot‘ or when one of the <binary list> keywords appears, a raw binary file is assumed whereby the keywords specify the binary format.

General binary data files fall into two basic classes, and some files may be of both classes depending upon how they are treated. There is that class for which uniform sampling is assumed and point coordinates must be generated. This is the class for which full control via the <binary list> keywords applies. For this class, the settings precedence is that command line parameters override in-file parameters, which override default settings. The other class is that set of files for which coordinate information is contained within the file or there is possibly a non-uniform sampling such as gnuplot binary.

Other than for the unique data files such as gnuplot binary, one should think of binary data as conceptually the same as ASCII data. Each point has columns of information which are selected via the ‘<using list>‘ associated with using. When no ‘format‘ string is specified, gnuplot will retrieve a number of binary variables equal to the largest column given in the ‘<using list>‘. For example, ‘using 1:3‘ will result in three columns being read, of which the second will be ignored. There are default using lists based upon the typical number of parameters associated with a certain plot type. For example, ‘with image‘ has a default of ‘using 1‘, while rgbimage has a default of ‘using 1:2:3‘. Note that the special characters for using representing point/line/index generally should not be used for binary data. There are keywords in <binary list> that control this.

— ARRAY —

Describes the sampling array dimensions associated with the binary file. The coordinates will be generated by gnuplot. A number must be specified for each dimension of the array. For example, ‘array=(10,20)‘ means the underlying sampling structure is two-dimensional with 10 points along the first (x) dimension and 20 points along the second (y) dimension. A negative number indicates that data should be read until the end of file. If there is only one dimension, the parentheses may be omitted. A colon can be used to separate the dimensions for multiple records. For example, ‘array=25:35‘ indicates there are two one-dimensional records in the file.

      Note:  Gnuplot version 4.2 used the syntax array=128x128 rather than
             array=(128,128). The older syntax is now deprecated, but may
             still work if your copy of gnuplot was built to support
             backwards compatibility.

— RECORD —

This keyword serves the same function as ‘array‘, having the same syntax. However, ‘record‘ causes gnuplot to not generate coordinate information. This is for the case where such information may be included in one of the columns of the binary data file.

— SKIP —

This keyword allows you to skip sections of a binary file. For instance, if the file contains a 1024 byte header before the start of the data region you would probably want to use

      plot '<file_name>' binary skip=1024 ...

If there are multiple records in the file, you may specify a leading offset for each. For example, to skip 512 bytes before the 1st record and 256 bytes before the second and third records

      plot '<file_name> binary record=356:356:356 skip=512:256:256 ...

— FORMAT —

The default binary format is a float. For more flexibility, the format can include details about variable sizes. For example, ‘format="%uchar%int%float"‘ associates an unsigned character with the first using column, an int with the second column and a float with the third column. If the number of size specifications is less than the greatest column number, the size is implicitly taken to be similar to the last given variable size.

Furthermore, similar to the using specification, the format can include discarded columns via the ‘*‘ character and have implicit repetition via a numerical repeat-field. For example, ‘format="%*2int%3float"‘ causes gnuplot to discard two ints before reading three floats. To list variable sizes, type ‘show datafile binary datasizes‘. There are a group of names that are machine dependent along with their sizes in bytes for the particular compilation. There is also a group of names which attempt to be machine independent.

— ENDIAN —

Often the endianess of binary data in the file does not agree with the endianess used by the platform on which gnuplot is running. Several words can direct gnuplot how to arrange bytes. For example ‘endian=little‘ means treat the binary file as having byte significance from least to greatest. The options are

              little:  least significant to greatest significance
                 big:  greatest significance to least significance
             default:  assume file endianess is the same as compiler
         swap (swab):  Interchange the significance.  (If things
                       don't look right, try this.)

Gnuplot can support "middle" ("pdp") endian if it is compiled with that option.

— FILETYPE —

For some standard binary file formats gnuplot can extract all the necessary information from the file in question. As an example, "format=edf" will read ESRF Header File format files. For a list of the currently supported file formats, type ‘show datafile binary filetypes‘.

There is a special file type called ‘auto‘ for which gnuplot will check if the binary file’s extension is a quasi-standard extension for a supported format.

Command line keywords may be used to override settings extracted from the file. The settings from the file override any defaults. (See ‘set datafile binary‘ for details.)

— AVS —

‘avs‘ is one of the automatically recognized binary file types for images. AVS is an extremely simple format, suitable mostly for streaming between applications. It consists of 2 longs (xwidth, ywidth) followed by a stream of pixels, each with four bytes of information alpha/red/green/blue.

— EDF —

‘edf‘ is one of the automatically recognized binary file types for images. EDF stands for ESRF Data Format, and it supports both edf and ehf formats (the latter means ESRF Header Format). More information on specifications can be found at

  http://www.edfplus.info/specs

See also ‘binary‘.

— KEYWORDS —

The following keywords apply only when generating coordinates. That is, when the keyword ‘array‘ is used.

— SCAN —

A great deal of confusion can arise concerning the relationship between how gnuplot scans a binary file and the dimensions seen on the plot. To lessen the confusion, conceptually think of gnuplot _always_ scanning the binary file point/line/plane or fast/medium/slow. Then this keyword is used to tell gnuplot how to map this scanning convention to the Cartesian convention shown in plots, i.e., x/y/z. The qualifier for scan is a two or three letter code representing where point is assigned (first letter), line is assigned (second letter), and plane is assigned (third letter). For example, ‘scan=yx‘ means the fastest, point-by-point, increment should be mapped along the Cartesian y dimension and the middle, line-by-line, increment should be mapped along the x dimension.

When the plotting mode is ‘plot‘, the qualifier code can include the two letters x and y. For ‘splot‘, it can include the three letters x, y and z.

There is nothing restricting the inherent mapping from point/line/plane to apply only to Cartesian coordinates. For this reason there are cylindrical coordinate synonyms for the qualifier codes where t (theta), r and z are analogous to the x, y and z of Cartesian coordinates.

— TRANSPOSE —

Shorthand notation for ‘scan=yx‘ or ‘scan=yxz‘.

— DX, DY, DZ —

When gnuplot generates coordinates, it uses the spacing described by these keywords. For example ‘dx=10 dy=20‘ would mean space samples along the x dimension by 10 and space samples along the y dimension by 20. ‘dy‘ cannot appear if ‘dx‘ does not appear. Similarly, ‘dz‘ cannot appear if ‘dy‘ does not appear. If the underlying dimensions are greater than the keywords specified, the spacing of the highest dimension given is extended to the other dimensions. For example, if an image is being read from a file and only ‘dx=3.5‘ is given gnuplot uses a delta x and delta y of 3.5.

The following keywords also apply only when generating coordinates. However they may also be used with matrix binary files.

— FLIPX, FLIPY, FLIPZ —

Sometimes the scanning directions in a binary datafile are not consistent with that assumed by gnuplot. These keywords can flip the scanning direction along dimensions x, y, z.

— ORIGIN —

When gnuplot generates coordinates based upon transposition and flip, it attempts to always position the lower left point in the array at the origin, i.e., the data lies in the first quadrant of a Cartesian system after transpose and flip.

To position the array somewhere else on the graph, the origin keyword directs gnuplot to position the lower left point of the array at a point specified by a tuple. The tuple should be a double for ‘plot‘ and a triple for ‘splot‘. For example, ‘origin=(100,100):(100,200)‘ is for two records in the file and intended for plotting in two dimensions. A second example, ‘origin=(0,0,3.5)‘, is for plotting in three dimensions.

— CENTER —

Similar to origin, this keyword will position the array such that its center lies at the point given by the tuple. For example, ‘center=(0,0)‘. Center does not apply when the size of the array is ‘Inf‘.

— ROTATE —

The transpose and flip commands provide some flexibility in generating and orienting coordinates. However, for full degrees of freedom, it is possible to apply a rotational vector described by a rotational angle in two dimensions.

The ‘rotate‘ keyword applies to the two-dimensional plane, whether it be ‘plot‘ or ‘splot‘. The rotation is done with respect to the positive angle of the Cartesian plane.

The angle can be expressed in radians, radians as a multiple of pi, or degrees. For example, ‘rotate=1.5708‘, ‘rotate=0.5pi‘ and ‘rotate=90deg‘ are equivalent.

If origin is specified, the rotation is done about the lower left sample point before translation. Otherwise, the rotation is done about the array ‘center‘.

— PERPENDICULAR —

For ‘splot‘, the concept of a rotational vector is implemented by a triple representing the vector to be oriented normal to the two-dimensional x-y plane. Naturally, the default is (0,0,1). Thus specifying both rotate and perpendicular together can orient data myriad ways in three-space.

The two-dimensional rotation is done first, followed by the three-dimensional rotation. That is, if R’ is the rotational 2 x 2 matrix described by an angle, and P is the 3 x 3 matrix projecting (0,0,1) to (xp,yp,zp), let R be constructed from R’ at the upper left sub-matrix, 1 at element 3,3 and zeros elsewhere. Then the matrix formula for translating data is v’ = P R v, where v is the 3 x 1 vector of data extracted from the data file. In cases where the data of the file is inherently not three-dimensional, logical rules are used to place the data in three-space. (E.g., usually setting the z-dimension value to zero and placing 2D data in the x-y plane.)

— BINARY EXAMPLES —

Examples:

      # Selects two float values (second one implicit) with a float value
      # discarded between them for an indefinite length of 1D data.
      plot '<file_name>' binary format="%float%*float" using 1:2 with lines

      # The data file header contains all details necessary for creating
      # coordinates from an EDF file.
      plot '<file_name>' binary filetype=edf with image
      plot '<file_name>.edf' binary filetype=auto with image

      # Selects three unsigned characters for components of a raw RGB image
      # and flips the y-dimension so that typical image orientation (start
      # at top left corner) translates to the Cartesian plane.  Pixel
      # spacing is given and there are two images in the file.  One of them
      # is translated via origin.
      plot '<file_name>' binary array=(512,1024):(1024,512) format='%uchar' \
           dx=2:1 dy=1:2 origin=(0,0):(1024,1024) flipy u 1:2:3 w rgbimage

      # Four separate records in which the coordinates are part of the
      # data file.  The file was created with a endianess different from
      # the system on which gnuplot is running.
      splot '<file_name>' binary record=30:30:29:26 endian=swap u 1:2:3

      # Same input file, but this time we skip the 1st and 3rd records
      splot '<file_name>' binary record=30:26 skip=360:348 endian=swap u 1:2:3