The PLplot metafile is a way to store and transport your graphical data for rendering at a later time or on a different system. A PLplot metafile is in binary format in order to speed access and keep storage costs reasonable. All data is stored in device-independent format (written as a stream of bytes); the resulting file is about as portable as a tektronix vector graphics file and only slightly larger.
Each PLplot metafile begins with a header string that identifies it as such, as well as the version number of the format since this may change in time. The utility for rendering the metafile, plrender, verifies that the input file is indeed a valid PLplot metafile, and that it "understands" the format the metafile is written in. plrender is part of the PLplot package and should be built at the time of building PLplot, and then put into your search path. It is capable of high speed rendering of the graphics file, especially if the output device can accept commands at a high rate (e.g. X windows).
The commands as written by the metafile driver at present are as follows:
INITIALIZE
CLOSE
SWITCH_TO_TEXT
SWITCH_TO_GRAPH
CLEAR
PAGE
NEW_COLOR
NEW_WIDTH
LINE
LINETO
ESCAPE
ADVANCE
Each command is written as a single byte, possibly followed by additional data bytes. The NEW_COLOR and NEW_WIDTH commands each write 2 data bytes, the LINETO command writes 4 data bytes, and the LINE command writes 8 data bytes. The most common instruction in the typical metafile will be the LINETO command, which draws a continuation of the previous line to the given point. This data encoding is not quite as efficient as the tektronix format, which uses 4 bytes instead of 5 here (1 command + 4 data), however the PLplot encoding is far simpler to implement and more robust. The ESCAPE function writes a second command character (opcode) followed by an arbitrary number of data bytes depending on the value of the opcode. Note that any data written must be in device independent form to maintain the transportability of the metafile so floating point numbers are not allowed.
The short usage message for plrender is printed if one inputs insufficient or invalid arguments, and is as follows:
% plrender
No filename specified.
Usage:
plrender [options] [files]
plrender options:
[-v] [-i name] [-b number] [-e number] [-p page]
PLplot options:
[-h] [-v] [-verbose] [-debug] [-dev name] [-o name] [-display name]
[-px number] [-py number] [-geometry geom] [-wplt xl,yl,xr,yr]
[-mar margin] [-a aspect] [-jx justx] [-jy justy] [-ori orient]
[-freeaspect] [-width width] [-bg color] [-ncol0 n] [-ncol1 n] [-fam]
[-fsiz size] [-fbeg number] [-finc number] [-fflen length] [-nopixmap]
[-db] [-np] [-server_name name] [-server_host name] [-server_port name]
[-user name]
Type plrender -h for a full description.
|
The longer usage message goes into more detail, and is as follows:
% plrender -h
Usage:
plrender [options] [files]
plrender options:
-v Print out the plrender version number
-i name Input filename
-b number Beginning page number
-e number End page number
-p page Plot given page only
If the "-i" flag is omitted, unrecognized input will assumed to be filename
parameters. Specifying "-" for the input or output filename means use stdin
or stdout, respectively. See the manual for more detail.
PLplot options:
-h Print out this message
-v Print out the PLplot library version number
-verbose Be more verbose than usual
-debug Print debugging info (implies -verbose)
-dev name Output device name
-o name Output filename
-display name X server to contact
-px number Plots per page in x
-py number Plots per page in y
-geometry geom Window size, in pixels (e.g. -geometry 400x300)
-wplt xl,yl,xr,yr Relative coordinates [0-1] of window into plot
-mar margin Margin space in relative coordinates (0 to 0.5, def 0)
-a aspect Page aspect ratio (def: same as output device)
-jx justx Page justification in x (-0.5 to 0.5, def 0)
-jy justy Page justification in y (-0.5 to 0.5, def 0)
-ori orient Plot orientation (0,2=landscape, 1,3=portrait)
-freeaspect Do not preserve aspect ratio on orientation swaps
-width width Sets pen width (1 <= width <= 10)
-bg color Background color (0=black, FFFFFF=white)
-ncol0 n Number of colors to allocate in cmap 0 (upper bound)
-ncol1 n Number of colors to allocate in cmap 1 (upper bound)
-fam Create a family of output files
-fsiz size Output family file size in MB (e.g. -fsiz 1.0)
-fbeg number First family member number on output
-finc number Increment between family members
-fflen length Family member number minimum field width
-nopixmap Don't use pixmaps in X-based drivers
-db Double buffer X window output
-np No pause between pages
-server_name name Main window name of PLplot server (tk driver)
-server_host name Host to run PLplot server on (dp driver)
-server_port name Port to talk to PLplot server on (dp driver)
-user name User name on remote node (dp driver)
All parameters must be white-space delimited. Some options are driver
dependent. Please see the PLplot reference document for more detail.
|
The options are generally self explanatory (family files are explained in the Section called Family File Output). Most of these options have default values, and for those that don't plrender will prompt the user. The -px and -py options are not so useful at present, because everything is scaled down by the specified factor --- resulting in labels that are too small (future versions of plrender might allow changing the label size as well).
Additional options may be added in future releases.