PdPlot Quick Start

First, get the latest version by clicking on "repository" in the sidebar. This will take you to a "git" revision control system. The most current entry will be at the top. There will be a link under "actions" labeled ".tar.gz". This will get you a compressed tar file of the project source code.

To build Pdplot, type "make depend" and then "make". If you like what you see, then run "make install" with sufficient permission to write in "/usr/local/". Pdplot keeps its font files in "/usr/local/lib/pdplot".

Normally you will plot by piping data to the helper script "/usr/local/bin/pd". It will create a pipe file in "/var/spool/sockets/pdplot". You may have to create this directory by hand the first time you run the program. From then on, pd will check for the existence of a pdplot daemon and will start a new one if needed, otherwise it will send the plot data through the pipe to the currently running pdplot program.

A simple way to test if things are working is to create a simple plot by typing:

    (echo 0 0; echo 1 1) | pd

Manual Page


PDPLOT(1:LOCAL)						       PDPLOT(1:LOCAL)



NAME
       pdplot - plot ascii data to an X window

SYNOPSIS
       Pdplot
       pd [-n] [-k] [-g ] [-p] [-r] [file1 file2...]

DESCRIPTION
       Pdplot reads ascii x-y pairs and commands from standard input to create
       a formatted plot of the data in an X11 window.  The input lines	should
       consist	of  either  an x-y pair or a formatting command, one per line.
       Blank lines and lines starting with "#" are ignored.

       The easiest way to invoke Pdplot under X11 is with  the	pd(1)  script,
       which  will handle creation of pipes and put Pdplot into the background
       so the display will not be erased when the data ends.  Additional plots
       can be made to the same graphics window with later calls to pd(1).

       pd(1)  accepts input from either a list of files from the command line,
       or from stdin (similiar to cat(1)).  With no options pd	will  start  a
       pdplot  daemon  if  none	 already exists, clear the window and plot the
       data.

OPTIONS
       -n     Do not clear the plot window before plotting new data.  New data
	      will  be	merged	with  the  old	dataset	 and  the data will be
	      rescaled if necessary.

       -g 
	      Write a bitdump of the  existing	window	to  .png.	  This
	      function requires the program pnmtopng(1) (from the Netpbm pack-
	      age) to be present in the search path.  This  is	equivalent  to
	      giving  the  graph    formatting  command in the plot data
	      file.

       -p 
	      Write a postscript dump of the  existing	window	to  .ps.
	      This  is	equivalent to putting a post  formatting command
	      in the input data file.

       -k     Kill any existing pdplot daemon and close the graphics window.

       -r     Force a refresh of the screen.

GENERAL USAGE
       After the X11 window is created, it can be resized and zoomed  in  sev-
       eral  ways.   The  normal  X11  resize  by stretching the frame or menu
       selection leaves the plotted value range unchanged.  Clicking the right
       mouse  button  at  two  locations  will	zoom in to that range.	If the
       clicks are outside the frame of the plot, the plot will be zoomed  out.
       Double  clicking	 at  the  same	x-y location will cause the data to be
       rescaled so that it is all within the frame (auto unzoom).

       If the keyword plot appears on the input, the data so far will be plot-
       ted.   If  the keyword clear appears, the window will be cleared, ready
       for another set of data.	 These two commands are used by	 pd  to	 allow
       reuse  of the same graphics window for additional plots or to add data.


FORMATTING COMMANDS
       The following formatting commands are available.	 Most of  them	should
       appear  before  any  data.   Some of them, such as the pen command, may
       appear among the data.

       Formatting commands and datapoints may be placed one per line.

       style {working|presentation}
	      This sets one of several basic modes.  The default  is  working,
	      which  uses  a  large drawing area, small default character size
	      and defaults to using a grid.  The alternative is	 presentation,
	      which is intended to provide legible slides or viewgraphs.  This
	      uses larger characters and a somewhat smaller data  region,  and
	      turns  off the grid.  The style command overrides earlier lower-
	      left, charsize and grid commands.	 Only the first	 character  of
	      the argument ( w, or p ) is needed.

       title top_label
	      top_label must be fewer than 150 characters.  Up to two lines of
	      title may be specified.  Titles too long to fit at  the  default
	      (or  specified)  character  size	will be drawn smaller so as to
	      fit.  Some special characters are available (see below).

       xscale [value] [axis_label]
       yscale [value] [axis_label]
	      The program divides the corresponding inputs by value and labels
	      the  corresponding  axis	with  axis_label.   The scale value is
	      applied when it is read.	Points that are read prior to the  x/y
	      scale command will not be scaled.	 Either the value or the label
	      may be omitted but at least one must appear on the command line.
	      For  example, if the x data are values around a few nanoseconds,
	      you might use:

		   xscale 1e-9 TIME (ns)

	      The label must have fewer than 150 characters.

       nextygraph [graph_number]
	      Pdplot can stack up to 10 graphs on one plot.  All graphs	 share
	      a	 common	 X  axis,  and	the  Y	axes are independently scaled,
	      labelled, etc.  The nextygraph command  directs  Pdplot  to  add
	      another  graph  and  subsequent  data, label and yscale commands
	      will be placed in that graph.

       noisotropic
       isotropic [aspect]
	      By default, Pdplot scales the X and Y  directions	 independently
	      to  fill the page.  If isotropic is given, Pdplot will force the
	      scales to be the same in X and Y by reducing  the	 size  of  the
	      plot frame in one directions.  If an aspect ratio is given, then
	      a square will be drawn aspect times higher than it is wide.

       label x y label_string
       label x% y% label_string
	      X and y values are given in scaled units.	 In the	 case  of  dbx
	      and  dby, the values should be in dB.  The label_string may con-
	      tain any of the special characters mentioned below.   The	 label
	      may  be placed outside of the normal plotting area.  The size of
	      the label may be changed with a labelsize command.  The  orient-
	      tion  of	the  label may be changed with a labeldir command.  In
	      the second case above, the label placement may be specified as X
	      and  Y  percentages  relative to the graphing region.  When com-
	      bined with data lines using %, this provides an easy way to draw
	      legends, etc.
       labeldir direction
	      This  defines the orientation of the labels.  The default direc-
	      tion is 0 degrees (horizontal).
       xset xmin xmax
       yset ymin ymax
	      This command allows the user to specify the range	 of  the  plot
	      independent  of the data.	 Both the minimum and the maximum must
	      be specified with each command, or automatic scaling is enabled.
	      If  only	one of the two axes is specified, automatic scaling of
	      the other axis will only consider data points  that  are	within
	      the specified range on the first axis.  maxxdiv n
       maxydiv n
	      N	 is  the  maximum  number  of  divisions  along the axis.  The
	      default is 7.  For example, if the data ranged from  0  to  100,
	      the  scale  would	 normally be 5 divisions of 20, but if max?div
	      were set to 10, there would be 10 divisions of 10.  The range of
	      n	 is  limited  between 2 and 50.	 The unit division is from the
	      set 1, 2, 2.5, 5, possibly multiplied by a power	of  10.	  Each
	      tick will land on an integer multiple of the unit division.

       charsize size
       scalesize size
       tagsize size
       titlesize size
       labelsize size
	      Characters are usually proportional to the sum of the lengths of
	      the axes.	 Size is a value between .1 and	 10  which  multiplies
	      the  default  size of the characters.  Charsize changes the size
	      of all the text, and each of the other commands changes the cor-
	      responding  kind	of text.  Tagsize scales the numeric labels at
	      the grid divisions.  Scalesize scales the axis  label  specified
	      by xscale or yscale.

       xgrid [xgridline] (vertical grid)
       ygrid [ygridline] (horizontal grid)
       grid [gridline] (full grid)
       nogrid (default)
	      These  commands draw a grid for the plot.	 A line type between 1
	      and 5 may be specified (see line below).

       xgridpen xgridpen (vertical grid)
       ygridpen ygridpen (horizontal grid)
       gridpen gridpen
       framepen framepen
	      Select a pen other than pen 1 for grid lines or the frame.   The
	      frame  includes  the axes, tags, scale labels, and titles.  This
	      is most useful on a pen plotter where a thinner  pen  is	to  be
	      used for the grid than for the frame.

       noback (default)
       back   If  noback  is  set,  the pen will lift for negative x motion so
	      that one datafile can have multiple curves.  If the back command
	      is given, the pen will stay down during negative x motion.  This
	      command may be among the data pairs.

       line n N is an integer between zero and five which specifies  the  type
	      of line to draw.
	    0  dots only at the data points
	    1  solid line (default)
	    2  dashed line
	    3  dotted line
	    4  dash dot line
	    5  long dash short dash

       Line  type 0 uses a square dot that is one device unit on a side.  This
       will usually plot as four pixels on graphics terminals.

       autoline
       noautoline (default)
	      If noback is set, the linetype for  each	new  trace  is	cycled
	      through  linetypes  1-5.	On monochrome displays, the default is
	      autoline.

       pen [n]
	      Change to pen n for the following	 data.	 The  number  of  pens
	      available	 depends  on  the  plotter.  In X11 and on the default
	      PAINTXL plotter model, 6 pens are allowed.  If no	 n  is	given,
	      the  next	 pen  is  selected, going back to pen 1 after the last
	      pen.  If n is larger than the  maximum  allowed,	pen  n-modulo-
	      max_n is used.

       logx, logy, loglog, dbx, dby, dbpx, dbpy, linx, liny
	      Use  a  logarithmic  scale  for the indicated axis.  dbx and dby
	      will plot 20*log10 of the variable, while	 dbpx  and  dbpy  will
	      plot  10*log10 of the variable.  linx and liny are used to reset
	      the mode if a second set of axes	is  used.   Any	 scale	factor
	      introduced by an xscale or yscale will still be applied.

       autopen (default)
       noautopen
	      If  noback  is  set,  the	 traces will cycle among the available
	      pens.

       symbol [symbol_number]
	      Begin a scatter plot with the  indicated	symbol.	  Unless  sym-
	      bol+line	is  active,  the normal line will not be drawn.	 If no
	      symbol name is given, the "next" symbol will be used.

       symbol+line
	      Turn on both symbols and lines — connect the dots.

       nosymbol
	      Turn off symbols, and turn on lines.  This negates  symbol+line.

       noline Turn  off	 lines,	 and  turn  on symbol mode.  This negates sym-
	      bol+line.

       symbolsize value
	      Change the size of the symbol, with value being a multiplier  on
	      the default size, which scales with the perimeter of the plot.

       autosymbol (default)
       noautosymbol
	      Change the symbol to the "next" symbol each time there is neg-
	      ative x motion.

       jump   The jump command causes a pen lift between the  two  surrounding
	      data  points.  ticklength [length] Tick marks along the axes are
	      normally scaled with the perimeter of the	 plotting  area.   The
	      length  will  multiply  the  normal  length of the ticks.	 If no
	      length is specified, ticks are suppressed.

       scaletol [tolerance] (both axes)
       xscaletol [tolerance]
       yscaletol [tolerance]
	      When the program selects a scale to fit the data, the  frame  of
	      the  plot	 is  normally  allowed to be slightly smaller than the
	      range of the data.  For example, if the data range  from	-.0001
	      to  100, the range for the corresponding scale will be from 0 to
	      100.  Scaletol sets the fraction of the  data  range  which  can
	      fall  outside  the  scale	 for  the  plot.  Its default value is
	      0.001.  If tolerance is not given, it is assumed to  be  0,  and
	      all  of  the  data points are guaranteed to be within the frame.
	      Negative values may be specified, which guarantees  a  clearance
	      between the data and the frame of the plot.

       noframe
	      The  drawing  of the axes will be suppressed.  Neither the scale
	      labels nor the titles will appear.  The  label  command  may  be
	      used to do annotation.

       nobox  The  box	around	the  data  region  will	 be suppressed.	 Scale
	      labels, grids and titles are not affected.

       graph 
	      Write a bitdump of the  existing	window	to  .png.	  This
	      function	requires  the  program	pnmtopng(1)  (from  the Netpbm
	      package) to be present in the search path.  The bitmap is dumped
	      at  the point that it appears in the file, so the command should
	      be placed at the very end of the data file.

       post 
	      Write a postcript dump of the existing window to .ps.  The
	      resulting	 file is in a fairly organized format.	In particular,
	      you may wish to search for the color definitions c1, c2, ... c15
	      to  make	modifications.	 The postscript file is autoscaled and
	      rotated to fit the page as well as possible.

SPECIAL CHARACTERS
       The following special command characters	 are  allowed  in  titles  and
       labels.

	    begin subscript	\[
	    end subscript	\]
	    begin superscript	\{
	    end superscript	\}
	    backspace one char	\<
	    forward one char	\>

       The following special characters are allowed in titles and labels.  All
       of them are taken from the Hershey simplex fonts.

	    GAMMA				    \G
	    DELTA				    \D
	    THETA				    \H
	    LAMBDA				    \L
	    XI					    \C
	    PI					    \P
	    SIGMA				    \S
	    UPSILON				    \Y
	    PHI					    \F
	    CHI					    \X
	    PSI					    \Q
	    OMEGA				    \W
	    OMEGA				    \O
	    alpha				    \a
	    beta				    \b
	    gamma				    \g
	    delta				    \d
	    epsilon				    \e
	    zeta				    \z
	    eta					    \y
	    theta1				    \@
	    iota				    \i
	    kappa				    \k
	    lambda				    \l
	    mu					    \m
	    mu					    \u
	    nu					    \n
	    xi					    \c
	    pi					    \p
	    rho					    \r
	    sigma				    \s
	    tau					    \t
	    phi					    \f
	    chi					    \x
	    psi					    \q
	    omega				    \w
	    omega				    \o
	    slash				    \\

FILES
       /usr/local/lib/NOTEDATA.F   ; font definition file
       /usr/local/lib/SYMBOL.F	   ; symbol+greek definition file

AUTHOR
       Pdplot was written by Rick Walker (walker@omnisterra.com).

       Pdplot is a shameless clone of the Autoplot program originally  written
       by  Bob	Jewett	at  UC Berkeley with subsequent enhancements at HP and
       Agilent Laboratories (by Konstantinos Konstantinides and Ken  Poulton).
       Most  input  data files written for Autoplot will produce useful if not
       virtually identical plots under Pdplot.	Pdplot	is  a  "from  scratch"
       implementation,	heavily leveraging code from PdPiglet, and is released
       under the GNU General Public License version 2.

DIFFERENCES WITH AUTOPLOT
       Autoplot is a general pen-plotter driver with an emphasis on HPGL  out-
       put.  Pdplot is primarily an X11 plot program and does not produce HPGL
       but has support for PNG and Postscript output.

       Autoplot referenced the	entire	Hershey	 font  database.  Pdplot  uses
       Piglet-style font definition files for characters and symbols.

       Autoplot cycles through 6 pen colors: 0=Black, 1=White, 2=Red, 3=Green,
       4=Blue, 5=Aqua,	6=Magenta,  7=White,  8=Red...	 and  so  on.	Pdplot
       defines	15 colors: White, 6 basic colors, 6 desaturated colors and two
       shades of grey.	In both systems Black can be explicitly called by  pen
       0, but is not part of the automatic pen cycle.

       In Pdplot, "noframe" followed by "grid" will produce a plot with just a
       grid and no frame or annotations.  Autoplot's noframe command overrides
       any further modification of scales or grids.

       Pdplot  allows the specification of symbols by index number in addition
       to name.

       The dimgrid, brightgrid and the graph, post commands do	not  exist  in
       autoplot.

       Autoplot	 tops  it's graphic window on every expose event causing it to
       pop up whenever an overlaying window is repositioned.  Pdplot only tops
       itself at a plot command.

       There  are minor pen usage differences between the two programs.	 While
       plotting in "autopen" and "noback" mode, if a "pen " command is made
       just  prior to a negative x-motion in the data, autoplot will honor the
       pen command and use pen , but pdplot	will  honor  the  negative  x-
       motion, thereby printing the next segment with pen .

       Pdplot  tries  hard to show all lines that would be visible inside x or
       yset ranges.  Autoplot will sometimes drop lines that have their defin-
       ing coordinates outside the range.

       This  version  of Pdplot does not implement the following Autoplot com-
       mands:

       topxscale, rightyscale,	labeloverlab,  nolabeloverlab,	labelsinframe,
       nolabelsinframe,	 swallowzero,  noswallowzero,  xswallowzero,  noxswal-
       lowzero, yswallowzero, noyswallowzero, lowerleft, xsize, ysize,	speed,
       rotate, binary


BUGS
       Cursor  coordinate  picking  probably  doesn't  yet work on log scales.
       Maxxdiv and Maxydiv commands are handled by the code,  but  not	parsed
       yet.   Multiple commands cannot yet be entered by using ";;" delimiters
       on a givein line.  Log scales only have ticks at decade	intervals  and
       do not yet use metric prefixes (10k 100k 1M 10M 100M 1G...).  No provi-
       sion has yet been made to handle two title lines.




							       PDPLOT(1:LOCAL)