www.delorie.com/gnu/docs/plotutils/plotutils_17.html

search

	Buy GNU books!

The Plotutils Package

3.2 plot command-line options

The plot filter plot translates GNU graphics metafiles to other formats. The `-T' option is used to specify the output format or display type. Files in metafile format are produced by GNU graph, pic2plot, tek2plot, plotfont, and other applications that use the GNU libplot graphics library. For technical details on the metafile format, see D. The Graphics Metafile Format.

Input file names may be specified anywhere on the command line. That is, the relative order of file names and command-line options does not matter. If no files are specified, or the file name `-' is specified, the standard input is read. An output file is written to standard output, unless the `-T X' option is specified. In that case the output is displayed in a window or windows on an X Window System display, and there is no output file.

The full set of command-line options is listed below. There are four sorts of option:

1. Options setting the values of drawing parameters.
2. Options relevant only to raw plot, i.e., relevant only if no display type or output format is specified with the `-T' option.
3. Options specifying the type of metafile format the input is in (for backward compatibility only).
4. Options requesting information (e.g., `--help').

Each option that takes an argument is followed, in parentheses, by the type and default value of the argument.

The following options set the values of drawing parameters.

`-T type'

`--display-type type'

(String, default "meta".) Select a display type or output format of type type, which may be one of the strings "X", "png", "pnm", "gif", "svg", "ai", "ps", "cgm", "fig", "pcl", "hpgl", "regis", "tek", and "meta". These refer respectively to the X Window System, PNG format, portable anymap (PBM/PGM/PPM) format, pseudo-GIF format, the new XML-based Scalable Vector Graphics format, the format used by Adobe Illustrator, idraw-editable Postscript, the WebCGM format for Web-based vector graphics, the format used by the xfig drawing editor, the Hewlett--Packard PCL 5 printer language, the Hewlett--Packard Graphics Language (by default, HP-GL/2), the ReGIS (remote graphics instruction set) format developed by DEC, Tektronix format, and device-independent GNU graphics metafile format.

`-p n'

`--page-number n'

(Positive integer.) Display only page number n, within the metafile or sequence of metafiles that is being translated.

Metafiles may consist of one or more pages, numbered beginning with 1. Also, each page may contain multiple `frames'. plot -T X, plot -T regis, or plot -T tek, which plot in real time, will separate successive frames by screen erasures. plot -T png, plot -T pnm, plot -T gif, plot -T svg, plot -T ai, plot -T ps, plot -T cgm, plot -T fig, plot -T pcl, plot -T hpgl, which do not plot in real time, will display only the last frame of any multi-frame page.

The default behavior, if `-p' is not used, is to display all pages. For example, plot -T X displays each page in its own X window. If the `-T png' option, the `-T pnm' option, the `-T gif' option, the `-T svg' option, the `-T ai' option, or the `-T fig' option is used, the default behavior is to display only the first page, since files in PNG, PNM, pseudo-GIF, SVG, AI, or Fig format may contain only a single page of graphics.

Most metafiles produced by the GNU plotting utilities (e.g., by raw graph) contain only a single page, consisting of two frames: an empty one to clear the display, and a second one containing graphics.

`-s'

`--merge-pages'

Merge all displayed pages into a single page, and also merge all `frames' within each displayed page.

This option is useful when merging together single-page plots from different sources. For example, it can be used to merge together plots obtained from separate invocations of graph. This is an alternative form of multiplotting (see section 2.4 Multiplotting: placing multiple plots on a single page).

`--bitmap-size bitmap_size'

(String, default "570x570".) Set the size of the graphics display in which the plot will be drawn, in terms of pixels, to be bitmap_size. This is relevant only to plot -T X, plot -T png, plot -T pnm, and plot -T gif, for all of which the size can be expressed in terms of pixels. The environment variable BITMAPSIZE may equally well be used to specify the size.

The graphics display used by plot -T X is a popped-up X window. Command-line positioning of this window on an X Window System display is supported. For example, if bitmap_size is "570x570+0+0" then the window will be popped up in the upper left corner.

If you choose a rectangular (non-square) window size, the fonts in the plot will be scaled anisotropically, i.e., by different factors in the horizontal and vertical direction. For this, plot -T X requires an X11R6 display. Any font that cannot be anisotropically scaled will be replaced by a default scalable font, such as the Hershey vector font "HersheySerif".

For backward compatibility, plot -T X allows the user to set the window size and position by setting the X resource Xplot.geometry, instead of `--bitmap-size' or BITMAPSIZE.

`--emulate-color option'

(String, default "no".) If option is "yes", replace each color in the output by an appropriate shade of gray. This is seldom useful, except when using `plot -T pcl' to prepare output for a PCL 5 device. (Many monochrome PCL 5 devices, such as monochrome LaserJets, do a poor job of emulating color on their own. They usually map HP-GL/2's seven standard pen colors, including even yellow, to black.) You may equally well request color emulation by setting the environment variable EMULATE_COLOR to "yes".

`--max-line-length max_line_length'

(Integer, default 500.) Set the maximum number of points that a polygonal line may contain, before it is flushed to the output device, to equal max_line_length. If this flushing occurs, the polygonal line will be split into two or more sub-lines, though the splitting should not be noticeable. Splitting will not take place if the line is the boundary of a filled polygon.

The reason for splitting long polygonal lines is that some display devices (e.g., old Postscript printers and HP-GL pen plotters) have limited buffer sizes. The environment variable MAX_LINE_LENGTH can also be used to specify the maximum line length. This option has no effect on plot -T tek or raw plot, since they draw polylines in real time and have no buffer limitations.

`--page-size pagesize'

(String, default "letter".) Set the size of the page on which the plot will be positioned. This is relevant only to plot -T svg, plot -T ai, plot -T ps, plot -T cgm, plot -T fig, plot -T pcl, and plot -T hpgl. "letter" means an 8.5in by 11in page. Any ISO page size in the range "a0"..."a4" or ANSI page size in the range "a"..."e" may be specified ("letter" is an alias for "a" and "tabloid" is an alias for "b"). "legal", "ledger", and "b5" are recognized page sizes also. The environment variable PAGESIZE can equally well be used to specify the page size.

For plot -T ai, plot -T ps, plot -T pcl, and plot -T fig, the graphics display (or `viewport') within which the plot is drawn will be, by default, a square region centered on the specified page. For plot -T hpgl, it will be a square region of the same size, but may be positioned differently. Either or both of the dimensions of the graphics display can be specified explicitly. For example, pagesize could be specified as "letter,xsize=4in", or "a4,xsize=10cm,ysize=15cm". The dimensions are allowed to be negative (a negative dimension results in a reflection).

The position of the graphics display, relative to its default position, may optionally be adjusted by specifying an offset vector. For example, pagesize could be specified as "letter,yoffset=1.2in", or "a4,xoffset=-5mm,yoffset=2.0cm". It is also possible to position the graphics display precisely, by specifying the location of its lower left corner relative to the lower left corner of the page. For example, pagesize could be specified as "letter,xorigin=2in,yorigin=3in", or "a4,xorigin=0.5cm,yorigin=0.5cm". The preceding options may be intermingled. plot -T svg and plot -T cgm ignore the "xoffset", "yoffset", "xorigin", and "yorigin" options, since SVG format and WebCGM format have no notion of the Web page on which the graphics display will ultimately be positioned. For more on page sizes, see C. Page Sizes and Viewport Sizes.

The following options set the initial values of additional drawing parameters. Any of these may be overridden by a directive in the metafile itself. In fact, these options are useful only when plotting old metafiles in the pre-GNU `plot(5)' format, which did not include such directives.

`--bg-color name'

(String, default "white".) Set the color used for the plot background to be name. This is relevant only to plot -T X, plot -T png, plot -T pnm, plot -T gif, plot -T cgm, plot -T regis, and plot -Tmeta. An unrecognized name sets the color to the default. For information on what names are recognized, see B. Specifying Colors by Name. The environment variable BG_COLOR can equally well be used to specify the background color.

If the `-T png' or `-T gif' option is used, a transparent PNG file or a transparent pseudo-GIF, respectively, may be produced by setting the TRANSPARENT_COLOR environment variable to the name of the background color. See section 3.3 Environment variables. If the `-T svg' or `-T cgm' option is used, an output file without a background may be produced by setting the background color to "none".

`-f font_size'

`--font-size font_size'

(Float, initial value device-dependent.) Set the initial size of the font used for rendering text, as a fraction of the width of the graphics display, to font_size.

`-F font_name'

`--font-name font_name'

(String, default "Helvetica" except for plot -T pcl, for which "Univers" is the default, and plot -T png, plot -T pnm, plot -T gif, plot -T hpgl, plot -T regis, plot -T tek, and raw plot, for all of which "HersheySerif" is the default.) Set the font initially used for text (i.e., for `labels') to font_name. Font names are case-insensitive. If the specified font is not available, the default font will be used. Which fonts are available depends on which `-T' option is used. For a list of all fonts, see A.1 Available text fonts. The plotfont utility will produce a character map of any available font. See section 6. The plotfont Utility.

`-W line_width'

`--line-width line_width'

(Float, default -1.0.) Set the thickness of lines, as a fraction of the size (i.e., minimum dimension) of the graphics display, to line_width. A negative value means that the default value provided by the GNU libplot graphics library should be used. This is usually 1/850 times the size of the display, although if `-T X', `-T png', `-T pnm', or `-T gif' is specified, it is zero. By convention, a zero-thickness line is the thinnest line that can be drawn. This is the case in all output formats. Note, however, that the drawing editors idraw and xfig treat zero-thickness lines as invisible.

plot -T tek and plot -T regis do not support drawing lines with other than a default thickness, and plot -T hpgl does not support doing so if the environment variable HPGL_VERSION is set to a value less than "2" (the default).

`--pen-color name'

(String, default "black".) Set the pen color to be name. An unrecognized name sets the pen color to the default. For information on what color names are recognized, see B. Specifying Colors by Name.

The following option is relevant only to raw plot, i.e., relevant only if no output type is specified with the `-T' option. In this case plot outputs a graphics metafile, which may be translated to other formats by a second invocation of plot.

`-O'

`--portable-output'

Output the portable (human-readable) version of GNU metafile format, rather than a binary version (the default). This can also be requested by setting the environment variable META_PORTABLE to "yes".

plot will automatically determine which type of GNU metafile format the input is in. There are two types: binary (the default) and portable (human-readable). The binary format is machine-dependent. See section D. The Graphics Metafile Format.

For compatibility with older plotting software, the reading of input files in the pre-GNU `plot(5)' format is also supported. This is normally a binary format, with each integer in the metafile represented as a pair of bytes. The order of the two bytes is machine dependent. You may specify that input file(s) are in plot(5) format rather than ordinary GNU metafile format by using either the `-h' option ("high byte first") or the `-l' option ("low byte first"), whichever is appropriate. Some non-GNU systems support an ASCII (human-readable) variant of plot(5) format. You may specify that the input is in this format by using the `-A' option. Irrespective of the variant, a file in plot(5) format includes only one page of graphics.

`-h'

`--high-byte-first-input'

Input file(s) are assumed to be in traditional `plot(5)' metafile format, with the high-order byte of each integer occurring first. This variant is uncommon.

`-l'

`--low-byte-first-input'

Input file(s) are assumed to be in traditional `plot(5)' metafile format, with the low-order byte of each integer occurring first. This variant is the most common.

`-A'

`--ascii-input'

Input file(s) are assumed to be in the ASCII variant of traditional `plot(5)' metafile format. This variant is rare: on some older systems, it is produced by a program called plottoa.

The following options request information.

`--help'

Print a list of command-line options, and then exit.

`--help-fonts'

Print a table of available fonts, and then exit. The table will depend on which display type or output format is specified with the `-T' option. plot -T X, plot -T svg, plot -T ai, plot -T ps, plot -T cgm, and plot -T fig each support the 35 standard Postscript fonts. plot -T svg, plot -T ai, plot -T pcl, and plot -T hpgl support the 45 standard PCL 5 fonts, and plot -T pcl and plot -T hpgl support a number of Hewlett--Packard vector fonts. All of the preceding, together with plot -T png, plot -T pnm, plot -T gif, plot -T regis, and plot -T tek, support a set of 22 Hershey vector fonts. Raw plot in principle supports any of these fonts, since its output must be translated to other formats with plot. The plotfont utility will produce a character map of any available font. See section 6. The plotfont Utility.

`--list-fonts'

Like `--help-fonts', but lists the fonts in a single column to facilitate piping to other programs. If no display type or output format is specified with the `-T' option, the full set of supported fonts is listed.

`--version'

Print the version number of plot and the plotting utilities package, and exit.