gradu(1)                                                 gradu(1)



NAME
       gradu - graphics dump



SYNOPSIS
       gradu [-dhv] [-a time]] [-b color]] [-c color]] [-s size]] [-t
       type]] [-x limit]] [-y limit]]  [-X  limit]]  [-Y  limit]]  [[--]]
       [[files...]]



DESCRIPTION
       gradu inputs a data stream of formatted text and renders a
       graphical  manifestation.  Various  command  line  options
       establish  initial  formatting  parameters.  The formatted
       text stream generally specifies  the  graphical  elements,
       but can also configure some formatting parameters.


OPTIONS
       -a time
              Animation  frame interval for GIF mode in millisec-
              onds.


       -b color
              Background color. The default is black.  color  can
              be  expressed  as a human-readable color word known
              to the system (magenta) or by a normal hex encoding
              ("#ff00ff").  When  specifying colors in hex format
              as an argument to  a  command  line  option,  quote
              marks are recommended to avoid conflicts with shell
              syntax. See .../plotutils/doc/colors.txt  for  more
              information about color specification.


       -c color
              Color  for  plotted  graphical elements. This over-
              rides the default which is white ("#ffffff").


       -d     Double buffering for animated X window output. This
              option  causes  output  to be suppressed until each
              frame is complete (signaled with a reset  command).
              The result is typically a smoother animation.


       -h     Help and usage message.


       -s size
              Size  of  bitmap.  The format for this is COLxROWS.
              The default is 570x570.  Additionally,  X  geometry
              specifications (WIDTHxHEIGHT+XOFF+YOFF) can be used
              in X mode to position the output.   This  parameter
              has  no  effect on vector output formats (PS, HPGL,
              etc).


       -t type
              Type of output. The libplot  library  supports  the
              following  output  format  types: X, png, pnm, gif,
              ps, hpgl, Xdrawable, svg, ai, fig, pcl, regis, tek,
              meta.  Only  the  first  five have been tested with
              gradu.


       -v     Verbose mode. Typically, the program generates  the
              desired  graphic  format on the standard output and
              the standard error stream is quiet unless there  is
              an  actual  error  (uh, one that has been accounted
              for!). With the verbose mode,  the  standard  error
              stream  receives  a  formatted  reiteration of each
              directive received from standard input.   This,  in
              effect, allows the user to "record" plot operations
              with gradu.  This is particularly useful as  a  way
              to  save  data  generated  by direct input with the
              console as in this example:
              $ gradu -v -- 22>> onthefly.grdu
              Another useful application of this  is  to  capture
              output  generated  arbitrarily for preservation and
              later analysis as in:
              $ foomon || gradu -v -- 22>> `date +%y.%m.log`
              The effect can be very much like using the Unix tee
              command  except that the actual data is reformatted
              into a form that gradu likes to see.  Also,  unlike
              the tee command, you can pipe the standard error to
              other programs  for  follow  up  parsing.  However,
              don't  send  that  back  to gradu since that causes
              ugly problems!


       -x limit
              Sets the minimum plottable horizontal user  coordi-
              nate.  Be careful to use quoting when setting nega-
              tive values which  could  be  confused  with  other
              options. (-x "-3.4")

       -y limit
              Sets  the  minimum  plottable vertical user coordi-
              nate. Be careful to use quoting when setting  nega-
              tive  values  which  could  be  confused with other
              options. (-y "-3.4")

       -X limit
              Sets the maximum plottable horizontal user  coordi-
              nate.

       -Y limit
              Sets  the  maximum  plottable vertical user coordi-
              nate.



INPUT SYNTAX
       gradu is designed to accomodate a wide variety of sensible
       input  styles  constrained  by  some  simple  rules. Input
       streams are parsed line by line. Each line typically  con-
       tains  a  command  specifier  and  arguments.  The command
       specifier is a single case-insensitive character. It  does
       not  matter where in the line the command is as long as it
       is the first plausible command found in a  left  to  right
       search  of  the  string. This implies that the command can
       come after some or all of the arguments  (which  must,  of
       course, be in the correct order). It also implies that the
       command and arguments can be delimited by  any  characters
       that won't cause confusion. See examples.


       <blank>
              A  blank input line causes the drawing buffer to be
              flushed. Sometimes  the  plotting  process  doesn't
              immediately  show  the  results  while in progress.
              Issuing a blank  line  insures  that  all  elements
              ordered  up until that point are delivered. This is
              quite useful  while  manually  entering  redirected
              data from the console.


       ##||!! comment
              Any  line  containing  a  #  or ! anywhere are com-
              pletely ignored. This has precedence  over  a  line
              containing a plausible command. See examples.


       @@||++++ [command] [relative args...]
              Any line containing a ++ or @ character anywhere in
              the line activates the relative coordinate  adress-
              ing  flag. Any command that supports relative coor-
              dinate addressing will then interpret arguments  as
              vectors  from  the  last  point and not the origin.
              This directive is used in  conjunction  with  other
              commands on a single line and has no effect on sub-
              sequent lines without the relative  modifier.  Note
              that  a  single  +  symbol  is considered part of a
              numerical input and simply translated to 0.


       a[rc] xc yc x0 y0 x1 y1
              Arc from point (x0,y0) to (x1,y1) with a center  of
              (xc,yc). Rotation sense is counter-clockwise.


       b[ox] x1 y1 x2 y2
              Box  (rectangular)  shape  with corners at (x1,y1),
              (x1,y2), (x2,y2), and (x2,y1).


       c[ircle] xc yc _r
              Circle with a center at (xc,yc) and a radius r.


       d[ot] _x _y
              Dot or single  pixel  (or  tiny  vector)  at  point
              (x,y).


       j[ump] _x _y
              Jump  to  point  (x,y)  without drawing anything in
              preparation  for  a  subsequent   command   (mainly
              "next").


       [line] x1 y1 x2 y2
              Line  from  (x1,y1)  to  (x2,y2). If there are four
              plausible numerical arguments and no possible  com-
              mand  is  specified,  then  the  'line'  command is
              implied.


       m[arker] _x _y [style [size]]
              Marker point at (x,y). The  style  argument  is  an
              integer  specifying  what  kind  of mark to produce
              while size is how big to make it. If  style  and/or
              size  are omitted, the last known value is used for
              the  missing  argument.  Common  style  codes  are:
              1=dot,  2=plus,  3=asterisk,  4=circle,  5=X-cross,
              6=square, 7=tri up, 8=diamond, 9=star, 10=tri down,
              11=starburst,  12=crosshair,  13=fancy  X, 14=fancy
              square,  15=fancy  diamond,  30=octagon,  31=filled
              octagon.  There  are  some other symbols between 15
              and 30 - YMMV. Style codes above 31 are interpreted
              as ASCII characters.


       [next] _x _y
              Next point in a line sequence from current position
              to (x,y). This can be used with 'jump'  to  produce
              intermittent  line segments. If less than 4 plausi-
              ble numeric arguments and no  possible  command  is
              specified, then the 'next' command is implied.


       o[val] xc yc rx ry ang
              Oval  or  ellipse with a center at (xc,yc), a width
              of rx, a height of ry, and a rotation of angle ang.


       r[eset]
              Reset clears the graphics display. For X window and
              GIF output, this allows  for  animation  possibili-
              ties. See options -a and -d.


       t[ext] _x _y  <newline>text
              Text  beginning at point (x,y). This command has an
              unusual format because it really prepares  for  the
              special  interpretation  of  the  next  line of the
              input stream. Therefore text  output  requires  two
              lines  from  the  input file. The first line issues
              the text command and positions the text.  The  line
              immediately  following  is  not  parsed  and inter-
              preted, but rather it is received as the string  to
              be plotted.


       p[rop] <subcommand> <arg>
              The  "property"  command  enters  a  submode  which
              allows the datastream to control various aspects of
              the  plotted  graphics beyond the geometry.  If "p"
              is scanned as the first viable command option, then
              the  line is rescanned looking for the first viable
              suboption. If a valid suboption is found, then  the
              line is scanned again for the correct argument (see
              Property Examples).

              [a]ngle textangle
                An angle measured  in  counter-clockwise  degrees
              from the positive x axis.

              [c]olor color
                A name from rgb.txt or 48-bit hex style.

              [e]ndcap mode
                (projecting  | round | butt) How the ends of wide
              lines will look.

              [f]ontsize value
                How high the font should be in user  coordinates.

              [j]oin mode
                (miter | round | bevel | triangular) How the end-
              point intersections of sequential  wide  line  seg-
              ments will look.

              [l]ine mode
                (solid | dotted | dotdashed | shortdashed | long-
              dashed | dotdotdashed | dotdotdotdashed  |  discon-
              nected)  Sets  linestyle  in  a  relatively easy to
              specify way.

              [w]idth value
                How wide subsequent graphical  elements  will  be
              plotted.


EXAMPLES
       General Format Examples-

       The following commands should all be legal:



              ##Example commands


              mmarker at=( 200,150 ) type=_3 size=50


              lline ( 100,100) to (150,150)


              @@-50,50


              @@nnext to ( 0,-100)


              jjump to=( 100,150)


              pp ww 15


              nnext to ( 0,150)


              pp cc pink


              ccircle cen=( 200,150) rad=40



       Property Examples-

       These commands are equivalent:

              pp ww 0.05

              PW0.05

              ppropwwidth 0.05

              0.05 ww pp

       Note, however, that

              ppropeerty width 0.05

       is problematic because the main command is parsed as a "p"
       correctly, but the subcommand is parsed as an "e"  (endcap
       mode).  The more extraneous letters in the input, the bet-
       ter chance for a conflict if features are added later.


       Delimiter Examples-

       This draws a circle:

              c$5,5$1$

       But this does nothing:

              c!5,5!1!

       Does NOT work because ! is a comment specifier  which  has
       precedence.


       Command Line Example-

              $ gradu -s 640x480+50+50 -t XX data* --

       Creates an X window of the specified geometry plotted with
       files starting with "data" and then waits  for  additional
       user input via the stdin (perhaps the console).


BUGS
       Documentation  with  the  phrase  "...projecting | round |
       butt..." sounds like a joke, but it's not!

       Error checking/handling is VERY weak!!!

       Ouch! Don't pipe the stderr  to  the  program  again  even
       though this seems vaugely plausible (like the plot of most
       time travel stories).

       Hmmm. Line mode property doesn't seem to work at all....

       Hmmm. Marker styles seem to not be  completely  unique  as
       implied by libplot documentation....

       Hmmm.  The  libplot "line" command doesn't seem to work at
       all. I had to cheat and use basically a "jump" and then  a
       "next" to acheive the same effect....


ACKNOWLEDGEMENTS
       This  entire  program is nothing but a way for a Unix user
       to lazily access the libplot programming  library  written
       by  Robert S. Maier, maintainer of the GNU plotting utili-
       ties package. I specifically used plotutils-2.4.1  and  if
       you want to have this program work, you should too.

       For  more  information  about  this goodly work check out:
       http://www.gnu.org/software/plotutils/plotutils.html
       http://www.math.arizona.edu/~rsm


AUTHOR
       This marginally useful program was written by:
              Chris XX Edwards
              <chris@xed.ch>



LWM                         2001.12.08                   gradu(1)
