1PLOT(1)                     GNU Plotting Utilities                     PLOT(1)
2
3
4

NAME

6       plot - translate GNU metafiles to other graphics formats
7

SYNOPSIS

9       plot [ options ] [ files ]
10

DESCRIPTION

12       plot translates files in GNU metafile format to other graphics formats,
13       or displays them on an X Window System display.  GNU metafile format is
14       a device-independent format for the storage of graphic data.  It is the
15       default  output  format  of   the   programs   graph(1),   pic2plot(1),
16       tek2plot(1),  and  plotfont(1),  and  is further documented in plot(5),
17       since it is an enhanced version of the traditional plot(5) format found
18       on  non-GNU  systems.   It  can also be produced by the GNU libplot 2-D
19       graphics export library (see plot(3)).
20
21       The output format is specified with the -T option.  The possible output
22       formats  and display types are the same as those supported by graph(1),
23       plotfont(1), pic2plot(1), and tek2plot(1).  If an output file  is  pro‐
24       duced, it is written to standard output.
25
26       Options and file names may be interspersed on the command line, but the
27       options are processed before the file names are read.  If --  is  seen,
28       it  is  interpreted  as  the  end of the options.  If no file names are
29       specified, or the file name - is encountered,  the  standard  input  is
30       read.
31

OPTIONS

33   General Options
34       -T type
35       --output-format type
36              Select  type as the output format.  It may be "X", "png", "pnm",
37              "gif", "svg", "ai", "ps", "cgm", "fig", "pcl", "hpgl",  "regis",
38              "tek", or "meta" (the default).  These refer respectively to the
39              X Window System, PNG (Portable Network Graphics) format,  porta‐
40              ble  anymap  format (PBM/PGM/PPM), a pseudo-GIF format that does
41              not use LZW encoding, the new XML-based Scalable Vector Graphics
42              format,  the  format  used  by  Adobe Illustrator, Postscript or
43              Encapsulated Postscript (EPS) that can be edited with  idraw(1),
44              CGM  format  (by default, confirming to the WebCGM profile), the
45              format used by the xfig(1) drawing editor,  the  Hewlett-Packard
46              PCL  5  printer language, the Hewlett-Packard Graphics Language,
47              ReGIS graphics format (which can be displayed by  the  dxterm(1)
48              terminal  emulator  or  by a VT330 or VT340 terminal), Tektronix
49              format (which can be displayed by the xterm(1)  terminal  emula‐
50              tor), and device-independent GNU metafile format itself.  Unless
51              type is "X", an output file is produced and written to  standard
52              output.
53
54              Omitting  the  -T  option  is  equivalent to specifying -T meta.
55              Translating from metafile format to itself is occasionally  use‐
56              ful, since there are two versions of metafile format (see the -O
57              option below).
58
59              A listing of the fonts available in any specified output  format
60              may  be obtained with the --help-fonts option (see below).  If a
61              requested font is unavailable, a default font  will  be  substi‐
62              tuted.   The  default  font is "Helvetica" for "X", "svg", "ai",
63              "ps", "cgm", and "fig", "Univers" for "pcl", and  "HersheySerif"
64              for "png", "pnm", "gif", "hpgl", "regis", "tek", and "meta".
65
66       -p n
67       --page-number n
68              Output  only  page  number n, within the metafile or sequence of
69              metafiles that is being translated.
70
71              Metafiles may consist of one or more pages,  numbered  beginning
72              with 1.  Also, each page may contain multiple `frames'.  plot -T
73              X, plot -T regis, and plot -T tek, which plot in real time, will
74              separate  successive  frames  by  screen erasures.  plot -T png,
75              plot -T pnm, plot -T gif, plot -T svg, plot -T ai, plot  -T  ps,
76              plot  -T  cgm, plot -T fig, plot -T pcl, and plot -T hpgl, which
77              do not plot in real time, will output only the last frame of any
78              multi-frame page.
79
80              The default behavior, if -p is not used, is to output all pages.
81              For example, plot -T X displays each page in its own  X  window.
82              If  the -T png, -T pnm, -T gif, -T ai, or -T fig option is used,
83              the default behavior is to output only the first nonempty  page,
84              since  files  in those output formats contain only a single page
85              of graphics.
86
87              Metafiles produced by graph(1) and plotfont(1)  contain  only  a
88              single  page  (page  #1), which consists of two frames: an empty
89              frame to clear the display, and a second frame that contains the
90              graphics.
91
92       -s
93       --merge-pages
94              Merge all displayed pages into a single page, and also merge all
95              `frames'.
96
97              This option is useful when merging  together  single-page  plots
98              from  different  sources.   For example, it can be used to merge
99              together plots obtained from separate invocations of graph(1).
100
101       --bitmap-size bitmap_size
102              Set the size of the graphics display in which the plot  will  be
103              drawn,  in  terms  of pixels, to be bitmap_size.  The default is
104              "570x570".  This is relevant only to plot -T  X,  plot  -T  png,
105              plot  -T pnm, and plot -T gif, all of which produce bitmaps.  If
106              you choose a rectangular (non-square) window size, the fonts  in
107              the plot will be scaled anisotropically, i.e., by different fac‐
108              tors in the horizontal and vertical directions.  For plot -T  X,
109              this  requires an X11R6 display.  Any font that cannot be scaled
110              in this way will be replaced by a default scalable font, such as
111              the vector font "HersheySerif".
112
113              The  environment variable BITMAPSIZE can equally well be used to
114              specify the window size.   For  backward  compatibility,  the  X
115              resource Xplot.geometry may be used instead.
116
117       --emulate-color option
118              If  option is yes, replace each color in the output by an appro‐
119              priate shade of gray.  This is seldom useful, except when  using
120              plot  -T  pcl to prepare output for a PCL 5 device.  (Many mono‐
121              chrome PCL 5 devices, such as monochrome LaserJets,  do  a  poor
122              job  of  emulating  color  on  their own.)  You may equally well
123              request color emulation by setting the environment variable EMU‐
124              LATE_COLOR to "yes".
125
126       --max-line-length max_line_length
127              Set  the maximum number of points that a polygonal line may con‐
128              tain, before it is flushed out, to be max_line_length.  If  this
129              flushing  occurs,  the  polygonal line will be split into two or
130              more sub-lines, though the splitting should not  be  noticeable.
131              The default value of max_line_length is 500.
132
133              The  reason for splitting long polygonal lines is that some dis‐
134              play devices (e.g., old Postscript printers and pen HP-GL  plot‐
135              ters)  have  limited  buffer  sizes.   The  environment variable
136              MAX_LINE_LENGTH can also be used to  specify  the  maximum  line
137              length.
138
139       --page-size pagesize
140              Set  the  size of the page on which the plot will be positioned.
141              This is relevant only to plot -T svg, plot -T ai,  plot  -T  ps,
142              plot  -T  cgm,  plot -T fig, plot -T pcl, and plot -T hpgl.  The
143              default is "letter", which means an 8.5 inch by  11  inch  page.
144              Any  ISO page size in the range "a0"..."a4" or ANSI page size in
145              the range "a"..."e" may be specified ("letter" is an  alias  for
146              "a"  and  "tabloid"  is an alias for "b").  "legal" and "ledger"
147              are recognized page sizes also.  The environment variable  PAGE‐
148              SIZE can equally well be used to specify the page size.
149
150              The  graphics  display  in  which  the  plot  is  drawn will, by
151              default, be a square region that occupies nearly the full  width
152              of  the  specified  page.   An alternative size for the graphics
153              display can be specified.  For example, the page size  could  be
154              specified        as       "letter,xsize=4in,ysize=6in",       or
155              "a4,xsize=5.0cm,ysize=100mm".  For all of the above except  plot
156              -T  hpgl,  the graphics display will, by default, be centered on
157              the page.  For all of the above except plot -T svg and  plot  -T
158              cgm, the graphics display may be repositioned manually, by spec‐
159              ifying the location of its lower left corner,  relative  to  the
160              lower left corner of the page.  For example, the page size could
161              be specified as "letter,xorigin=2in,yorigin=3in",  or  "a4,xori‐
162              gin=0.5cm,yorigin=0.5cm".   It  is  also  possible to specify an
163              offset vector.  For example, the page size could be specified as
164              "letter,xoffset=1in",  or "letter,xoffset=1in,yoffset=1.2in", or
165              "a4,yoffset=-1cm".  In SVG format and WebCGM format it is possi‐
166              ble  to  specify  the  size of the graphics display, but not its
167              position.
168
169       --rotation angle
170              Rotate the graphics display by angle degrees.  Recognized values
171              are  "0", "90", "180", and "270".  "no" and "yes" are equivalent
172              to "0" and "90", respectively.  The environment  variable  ROTA‐
173              TION can also be used to specify a rotation angle.
174
175   Parameter Initialization Options
176       The  following  options  set  the initial values of drawing parameters.
177       However, all of these may be overridden by directives  in  a  metafile.
178       In fact, these options are useful primarily when plotting old metafiles
179       in the traditional (pre-GNU) plot(5) format, which did not support such
180       directives.
181
182       --bg-color name
183              Set  the  color  initially  used  for the background to be name.
184              This is relevant only to plot -T X, plot -T png,  plot  -T  pnm,
185              plot  -T  gif,  plot -T svg, plot -T cgm, and plot -T regis.  An
186              unrecognized name sets  the  color  to  the  default,  which  is
187              "white".   The environment variable BG_COLOR can equally well be
188              used to specify the background color.
189
190              If the -T png or -T gif option is used, a transparent  PNG  file
191              or  a  transparent  pseudo-GIF, respectively, may be produced by
192              setting the TRANSPARENT_COLOR environment variable to  the  name
193              of  the  background  color.   If  the -T svg or -T cgm option is
194              used, an output file without a background  may  be  produced  by
195              setting the background color to "none".
196
197       -f size
198       --font-size size
199              Set the size of the font initially used for rendering text, as a
200              fraction of the width of the graphics display, to be size.   The
201              default is 0.0525.
202
203       -F name
204       --font-name name
205              Set the font initially used for text to be name.  Font names are
206              case-insensitive.  If the specified font is not  available,  the
207              default  font  will be used.  Which fonts are available, and the
208              default font, depend  on  which  -T  option  is  specified  (see
209              above).   A  list  of  available  fonts can be obtained with the
210              --help-fonts option (see below).
211
212       -W line_width
213       --line-width line_width
214              Set the initial width of lines, as a fraction of  the  width  of
215              the  display,  to  be line_width.  A negative value means that a
216              default value should be used.  This value  is  format-dependent.
217              The  interpretation  of zero line width is also format-dependent
218              (in some output formats, a zero-width line is the thinnest  line
219              that can be drawn; in others, a zero-width line is invisible).
220
221       --pen-color name
222              Set the initial pen color to be name.  An unrecognized name sets
223              the pen color to the default, which is "black".
224
225   Options for Metafile Output
226       The following option is relevant only if the -T option is omitted or if
227       -T meta is used.  In this case the output of plot, like the input, will
228       be in GNU graphics metafile format.
229
230       -O
231       --portable-output
232              Output the portable (human-readable)  version  of  GNU  metafile
233              format,  rather than the binary version (the default).  The for‐
234              mat of the binary version is machine-dependent.
235
236   Options for Backward Compatibility
237       By default, plot assumes that its  input  file(s)  are  in  either  the
238       binary version or the portable version of GNU metafile format.  You may
239       specify that the input is, instead, in the traditional  Unix  (pre-GNU)
240       graphics  metafile  format, which is documented in plot(5).  The tradi‐
241       tional graphics metafile format was produced  by  pre-GNU  versions  of
242       graph(1).
243
244       -h
245       --high-byte-first-input
246              Input file(s) are assumed to be in the binary, `high byte first'
247              version of traditional metafile format.  This variant is  uncom‐
248              mon.
249
250       -l
251       --low-byte-first-input
252              Input  file(s) are assumed to be in the binary, `low byte first'
253              version of traditional metafile format.   This  variant  is  the
254              most common.
255
256       -A
257       --ascii-input
258              Input  file(s)  are  assumed to be in the ASCII (human-readable)
259              variant of traditional metafile format.  On some older Unix sys‐
260              tems, this variant was produced by plottoa(1).
261
262   Informational Options
263       --help Print a list of command-line options, and exit.
264
265       --help-fonts
266              Print  a  table  of  available  fonts, and exit.  The table will
267              depend on which output format is specified with the  -T  option.
268              plot -T X, plot -T svg, plot -T ai, plot -T ps, plot -T cgm, and
269              plot -T fig each support the 35 standard Postscript fonts.  plot
270              -T  svg,  plot  -T pcl, and plot -T hpgl support the 45 standard
271              PCL  5  fonts,  and  the  latter  two  support   a   number   of
272              Hewlett-Packard  vector  fonts.   All  seven support a set of 22
273              Hershey vector fonts, as do plot -T png, plot -T  pnm,  plot  -T
274              gif,  plot  -T regis, and plot -T tek.  plot without a -T option
275              in principle supports any of these fonts, since its output  must
276              be translated to other formats by a further invocation of plot.
277
278              The plotfont(1) utility may be used to obtain a character map of
279              any supported font.
280
281       --list-fonts
282              Like --help-fonts, but lists the fonts in  a  single  column  to
283              facilitate  piping  to  other  programs.  If no output format is
284              specified with the -T option, the full set of supported fonts is
285              listed.
286
287       --version
288              Print  the  version  number  of  plot and the plotting utilities
289              package, and exit.
290

ENVIRONMENT

292       The  environment  variables  BITMAPSIZE,   PAGESIZE,   BG_COLOR,   EMU‐
293       LATE_COLOR,  MAX_LINE_LENGTH  and  ROTATION  serve  as  backups for the
294       options  --bitmap-size,   --page-size,   --bg-color,   --emulate-color,
295       --max-line-length,  and  --rotation, respectively.  The remaining envi‐
296       ronment variables are specific to individual output formats.
297
298       plot -T X, which pops up a window on an X  Window  System  display  and
299       draws  graphics  in  it,  checks the DISPLAY environment variable.  Its
300       value determines the display that will be used.
301
302       plot -T png and plot -T gif, which produce output  in  PNG  format  and
303       pseudo-GIF  format respectively, are affected by the INTERLACE environ‐
304       ment variable.  If its value is "yes", the output will  be  interlaced.
305       Also,  if the TRANSPARENT_COLOR environment variable is set to the name
306       of a color, that color will be treated as transparent in the output.
307
308       plot -T pnm, which produces output  in  portable  anymap  (PBM/PGM/PPM)
309       format,  is  affected by the PNM_PORTABLE environment variable.  If its
310       value is "yes", the output will be in a  human-readable  format  rather
311       than binary (the default).
312
313       plot  -T cgm, which produces output in CGM (Computer Graphics Metafile)
314       format, is affected by the CGM_MAX_VERSION and CGM_ENCODING environment
315       variables.   By  default,  it  produces a binary-encoded version of CGM
316       version 3 format.  For backward compatibility, the version  number  may
317       be  reduced  by setting CGM_MAX_VERSION to "2" or "1".  Irrespective of
318       version, the output CGM file will use  the  human-readable  clear  text
319       encoding if CGM_ENCODING is set to "clear_text".  However, only binary-
320       encoded CGM files conform to the WebCGM profile.
321
322       plot -T pcl, which produces PCL 5 output for  Hewlett-Packard  printers
323       and  plotters,  is affected by the environment variable PCL_ASSIGN_COL‐
324       ORS.  It should be set to "yes" when producing PCL 5 output for a color
325       printer  or other color device.  This will ensure accurate color repro‐
326       duction by giving the output device complete freedom in assigning  col‐
327       ors,  internally, to its "logical pens".  If it is "no" then the device
328       will use a fixed set of colored pens, and will emulate other colors  by
329       shading.   The  default is "no" because monochrome PCL 5 devices, which
330       are much more common than colored ones, must  use  shading  to  emulate
331       color.
332
333       plot  -T hpgl, which produces Hewlett-Packard Graphics Language output,
334       is affected by several environment variables.  The  most  important  is
335       HPGL_VERSION,  which  may  be  set to "1", "1.5", or "2" (the default).
336       "1" means that the output should be generic HP-GL, "1.5" means that the
337       output  should  be  suitable  for  the HP7550A graphics plotter and the
338       HP758x, HP7595A and HP7596A drafting plotters (HP-GL with some  HP-GL/2
339       extensions),  and  "2"  means that the output should be modern HP-GL/2.
340       If the version is "1" or "1.5" then the only available  fonts  will  be
341       vector  fonts, and all lines will be drawn with a default width (the -W
342       option will not work).  Additionally, if the version is  "1"  then  the
343       filling  of  arbitrary  curves  with  solid color will not be supported
344       (circles and rectangles aligned with the coordinate axes may be filled,
345       though).
346
347       The  position  of  the plot -T hpgl graphics display on the page can be
348       rotated 90 degrees counterclockwise by setting the HPGL_ROTATE environ‐
349       ment  variable to "yes".  This is not the same as the rotation obtained
350       with the --rotation option, since it both rotates the graphics  display
351       and  repositions  its  lower  left  corner toward another corner of the
352       page.  Besides "no" and "yes", recognized values  for  HPGL_ROTATE  are
353       "0",  "90", "180", and "270".  "no" and "yes" are equivalent to "0" and
354       "90", respectively.  "180" and "270" are supported only if HPGL_VERSION
355       is "2" (the default).
356
357       By  default,  plot  -T  hpgl will draw with a fixed set of pens.  Which
358       pens are present may be specified by setting the HPGL_PENS  environment
359       variable.   If  HPGL_VERSION  is "1", the default value of HPGL_PENS is
360       "1=black"; if HPGL_VERSION is  "1.5"  or  "2",  the  default  value  of
361       HPGL_PENS  is "1=black:2=red:3=green:4=yellow:5=blue:6=magenta:7=cyan".
362       The format should be self-explanatory.  By setting  HPGL_PENS  you  may
363       specify  a  color  for  any pen in the range #1...#31.  All color names
364       recognized by the X Window System may be used.  Pen #1 must  always  be
365       present,  though  it  need  not  be  black.  Any other pen in the range
366       #1...#31 may be omitted.
367
368       If HPGL_VERSION is "2" then plot -T hpgl will also be affected  by  the
369       environment  variable  HPGL_ASSIGN_COLORS.  If its value is "yes", then
370       plot -T hpgl will  not  be  restricted  to  the  palette  specified  in
371       HPGL_PENS:  it  will  assign  colors  to  "logical  pens"  in the range
372       #1...#31, as needed.  The default value  is  "no"  because  other  than
373       color  LaserJet  printers  and  DesignJet  plotters,  not  many HP-GL/2
374       devices allow the assignment of colors to logical pens.
375
376       Opaque filling and the drawing of visible  white  lines  are  supported
377       only   if   HPGL_VERSION   is   "2"   and   the   environment  variable
378       HPGL_OPAQUE_MODE is "yes" (the default).  If its  value  is  "no"  then
379       white lines (if any), which are normally drawn with pen #0, will not be
380       drawn.  This feature is to accommodate older HP-GL/2 devices.   HP-GL/2
381       pen  plotters, for example, do not support opacity or the use of pen #0
382       to draw visible white lines.  Some older HP-GL/2 devices may, in  fact,
383       malfunction if asked to draw opaque objects.
384
385       plot  -T  tek, which produces output for a Tektronix terminal or emula‐
386       tor, checks the TERM environment variable.  If the value of TERM  is  a
387       string  beginning  with "xterm", "nxterm", or "kterm", it is taken as a
388       sign that plot is running in an X Window System VT100  terminal  emula‐
389       tor: a copy of xterm(1), nxterm(1), or kterm(1).  Before drawing graph‐
390       ics, plot -T tek will emit an escape sequence that causes the  terminal
391       emulator's auxiliary Tektronix window, which is normally hidden, to pop
392       up.  After the graphics are drawn, an escape sequence that returns con‐
393       trol  to the original VT100 window will be emitted.  The Tektronix win‐
394       dow will remain on the screen.
395
396       If the value of TERM is a string beginning with  "kermit",  "ansi.sys",
397       or "nansi.sys", it is taken as a sign that plot is running in the VT100
398       terminal emulator provided by the MS-DOS version of kermit(1).   Before
399       drawing  graphics,  plot  -T  tek  will  emit  an  escape sequence that
400       switches the terminal emulator to Tektronix mode.  Also,  some  of  the
401       Tektronix control codes emitted by plot -T tek will be kermit-specific.
402       There will be a limited amount of color support, which is not  normally
403       the  case  (the 16 `ansi.sys' colors will be supported).  After drawing
404       graphics, plot -T tek will emit an escape  sequence  that  returns  the
405       emulator  to  VT100 mode.  The key sequence `ALT minus' can be employed
406       manually within kermit to switch between the two modes.
407

SEE ALSO

409       graph(1), pic2plot(1), tek2plot(1), plotfont(1), plot(3), plot(5),  and
410       "The GNU Plotting Utilities Manual".
411

AUTHORS

413       plot was written by Robert S. Maier (rsm@math.arizona.edu).
414

BUGS

416       Email bug reports to bug-gnu-utils@gnu.org.
417
418
419
420FSF                                Jun 2000                            PLOT(1)
Impressum