The Personal Web Pages of Chris X. Edwards

gradu - man page

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 milliseconds.
-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 overrides 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 - 2> onthefly.grdu Another useful application of this is to capture output generated arbitrarily for preservation and later analysis as in: $ foomon | gradu -v - 2> `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 coordinate.
-y limit: Sets the minimum plottable vertical user coordinate.
-X limit: Sets the maximum plottable horizontal user coordinate.
-Y limit: Sets the maximum plottable vertical user coordinate.

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 contains 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.

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 completely 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 adressing flag. Any command that supports relative coordinate 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 subsequent lines without the relative modifier.

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 command 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 plausible 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 possibilities. 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 interpreted, 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).

[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 endpoint intersections of sequential wide line segments will look.
[l]ine mode: (solid | dotted | dotdashed | shortdashed | longdashed | dotdotdashed | dotdotdotdashed | disconnected) 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
marker at=( 200,150 ) type=3 size=50
line ( 100,100) to (150,150)
@-50,50
@next to ( 0,-100)
jump to=( 100,150)
p w 15
next to ( 0,150)
p c pink
circle cen=( 200,150) rad=40

Property Examples- These commands are equivalent:

              p w 0.05
              PW0.05
              propwidth 0.05
              0.05 w p

Note, however, that

              property 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 better 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 X 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 utilities 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 X Edwards

Return to Main Page *** Return to gradu Page

This page was created with only free, open-source, publicly licensed software.
This page was designed to be viewed with any browser on any system.

Chris X. Edwards ~ May 2002