Graphics Tools

Drawing a Graph

The following functions are declared in the header file simple_plot.h. To use these functions, include simple_plot.h in your C program and compile using the system ``Cgfx'' command, which will find the proper header files and use the correct graphics libraries.

void draw_box(float xmin, float xmax, char *xlabel,
	      float ymin, float ymax, char *ylabel); 

void add_label(char *label);

void set_color(char *color);

void plot(float *x, float *y, int n);

void move_to(float x, float y);

void draw_to(float x, float y);

void point(float x, float y, float size);

void get_mouse(float *x, float *y);

int check_mouse();

void wait_for_mouse();

void pause(int time);

void clear_graphics();

void exit_graphics();

Thus, to perform the actions listed above for the sine function, we can use the following program:

#include <stdio.h>
#include <math.h>

#include "simple_plot.h"

#define N_POINTS 1000
#define XMIN 	 0
#define XMAX 	 (4 * M_PI)	/* this is just 4 PI; M_PI defined in math.h */

main()
{
    int i;
    double x;

    set_color("black");		/* (this is the default) */

    draw_box(XMIN, XMAX, "x", -1, 1, "sin(x)");
    add_label("plot of sin(x) versus x");

    move_to(XMIN, sin(XMIN));
    set_color("red");
    for (i = 0; i < N_POINTS; i++) {
	x = XMIN + i * (XMAX - XMIN) / (N_POINTS - 1);
	draw_to(x, sin(x));
    }

    exit_graphics();
}

The plot_data program accepts as input columns of data in character, integer, or floating-point format. It selects two columns, then performs all the operations listed above to produce a graph on the X-terminal. If the above program (producing x, sin x and cos x) has been compiled and called trig, then we can plot a graph of sin x simply by typing

	trig | plot_data

By default, plot_data plots column 1 as the x (horizontal) axis, column 2 as the y (vertical) axis. Its defaults are selected so that it does something ``reasonable'' with the minimum of user input.

Suppose we want a graph of cos x instead. To specify the columns to plot, use the command-line switch -c xcol ycol. This will result in xcol being plotted as x, ycol as y (so the default is xcol = 1, ycol = 2). Thus, we would say:

	trig | plot_data  -c 1 3

By default, the limits on the x and y axes are taken from the data. To override this and set your own, use the -l xmin xmax ymin ymax switch, which forces the range on the x-axis to be [xmin, xmax] and that on the y-axis to be [ymin, ymax].

There are several more options to allow you to control the appearance of your graph. Here is the complete list.

        -c xcol ycol1 ycol2 ycol3...
                        plot data in xcol horizontally, ycol1, ycol2,
			ycol3,... vertically [1 2]
        -c[c][xy]       crop [x or y] data to plot limits
        -C color1 color2 color3...
                        specify line/point colors for the columns set
			by "-c" [all black]
        -e              echo current settings
        -h header       specify overall label for plot [none]
        -i              ignore inline commands [don't ignore]
        -l xmin xmax ymin ymax  specify limits for plot [get from data]
        -ll             force plot lines only [plot lines]
        -L scale        specify limits to be +/- scale for both axes
        -N nmax         specify maximum number of points to store [50000]
        -o              echo stdin to stdout [do not echo]
        -O xo yo        specify top left corner of plotting box [150, 50]
        -p              toggle plot points only [plot lines]
        -pp             force plot points only [plot lines]
        -P size         specify point size, in x-axis units [0 ==> pixel]
        -q              suppress most output [don't suppress]
        -Q              quit
        -s xs ys        specify box size [500, 500]
        -S skip         skip leading lines [0]
        -t ntrail       specify number of trailing points [infinite]
        -w[w][xy]       wrap [x or y] data to plot limits
        -W              wait for keyboard input [inline only]
        -x xlabel       specify label for x-axis ["column 'xcol'"]
        -X              clear the display and redraw axes [inline only]
        -y ylabel       specify label for y-axis ["column 'ycol1...'"]
        -z zcol         specify column for color data [none]

Most of the above options are fairly self-explanatory. One useful feature of the program is that it can read in several columns of data, and plot the first on the horizontal axis, all the others vertically. The -C option allows each graph to be plotted in a different color (specified as standard X color names -- red, blue, green, etc.), if desired.

Alternatively, plot_data can read in three columns of data (x, y, and z, say) and plot y against x, choosing the color of each point according to the value of the data in z. The mapping between z-value and color is presently fairly rudimentary, but improvements are in the works.

The limits for the graphs may be specified on the command line, in which case plot_data draws the axes first and plots points as they become available, allowing you to see the plot evolve, or to make animations (-t option). Otherwise, plot_data must determine the limits from the input data, so nothing is plotted until the entire data stream is read.

Some examples (assume that the program data produces the stream of data to plot):

• To plot column 3 as x, columns 2 and 7 as y, coloring the plots red and green, labeling the x and y axes as "X" and "Y", and setting the limits on the axes to be [-1, 1] and [0, 1]:

  	data  |  plot_data  -c 3 2 7  -C red green  -x X -y Y  -l -1 1 0 1
  

• To plot column 1 as x, column 2 as y (the default), plotting points only and drawing them in red:

  	data  |  plot_data  -p  -C red
  

• To plot column 4 as x, column 5 as y, making the plot almost fill the entire screen and coloring the data according to the contents of column 7:

  	data  |  plot_data  -c 4 5  -s 800 800  -z 7
  

Finally, the current version of plot_data accepts most of the above command-line options as embedded commands in the input data stream itself, allowing the user to exercise run-time control over the display. For example, if the command line indicates that a single column is to be plotted in the vertical direction, and that the data are to be plotted as lines, then if the data stream contains

        .
        .
        .
        x  y  z
        x  y  z
        x  y  z
	-C red -p
        x  y  z
        x  y  z
        .
        .
        .

In order to to use inline commands, it is necessary that a window be opened for plotting at the start of input, not at the end, and this requires that some scaling information be provided on the command line. (If no such information is avaliable, then plot_data must obtain limits from the data, so the entire graph is drawn after the data are read and inline commands are ignored.) However, since the limits themselves can be set by inline commands, all that is really necessary is for plot_data to be forced to open a window, so a simple command like

	plot_data -L

	-c 3 2 7  -C red green  -x X -y Y  -l -1 1 0 1

	data | plot_data -L

Getting Hardcopy

	xwd  |  xpr  |  lpr

	convert  x:  ps:-  |  lpr

Unlike plot_data, mcdraw prompts the user for all input data -- filenames, columns to plot, output device (which doesn't have to be an X-display), and so on -- then draws the graph and waits for more input. Its original purpose was to produce publication-quality plots in a simple fashion. As a result, it has better fonts and heuristics for deciding what ``looks right'' than exist in plot_data. However, it has expanded in scope over the years, and can now do quite sophisticated operations, such as data reduction, array arithmetic, curve fitting, among others.

A typical mcdraw session, to produce a plot similar to the first example shown above, might look like:

	mcdraw:	file DATA	# open a data file called DATA
	mcdraw:	c 3 2		# get x from column 3, y from column 2
	mcdraw:	lim -1 1 0 1	# set limits on x and y
	mcdraw:	de x		# initialize graphics in X-windows
	mcdraw:	xl X		# specify the x-label as "X"
	mcdraw:	yl Y		# specify the y-label as "Y"
	mcdraw:	box		# draw a box, with labelled axes, etc.
	mcdraw:	plot		# plot y(x)
	mcdraw:	la LABEL	# put an overall label ("LABEL") on the figure.
	mcdraw:	quit		# exit from MCDRAW.

	mcdraw:	f DATA; c 3 2; l -1 1 0 1; de x; xl X; yl Y; b; p; q

On our systems, the color resolution of our screens allows us to display up to 256 colors simultaneously. The number is chosen because integers in the range 0 to 255 can be represented using a single byte of data--an unsigned char in C. Of course, there are many ways to choose these colors. The mapping between the integers 0 to 255 and the final color that appears on the display is called a color map. The standard color map we use looks like this:

There is no particular reason for this choice--it is simply convenient. Small numbers correspond to blue, large numbers to red, and intermediate numbers to intermediate colors in the ``spectrum''. The programs mcdraw and make_image (described in a moment) allow you to change the color map to one of your own, if you so desire.

To X, an image is a collection of bytes, one per pixel, along with a color map telling the display how to ``paint'' the screen. There are many different image formats in use--gif, jpeg, miff, xpn, to name but a few. Fortunately, we don't have to know how to construct them all. The program convert allows us to turn one into another.

To assist in turning your data into an image, we have provinded a simple program called make_image. This program takes a stream of data (fdrom stdin) representing your image (scanned left to right, top to bottom), adds a header describing the color map (the standard one, by default), and writes the image to stdout. The data may be float (the default), int, or char, and are assumed already to be scaled to lie in the range 0 to 255. Thus, to make a simple image, assuming that data produces the correct input, just type:

	data  |  make_image  -s XSIZE YSIZE  > image

The file created my make_image is in so-called ``Sun rasterfile'' format. This format has no particular advantage, except that it is simple and easy to code. To make, say, a GIF file, use convert:

	convert  image  image.gif

	data  |  make_image  -s XSIZE YSIZE  |  convert - image.gif

	-c	  incoming data are in char form
	-i	  incoming data are in int form
	-f	  incoming data are in float form [default]
	-m file	  read the colormap from the specified file
	-p	  pad the image to even dimensions (Sun rasterfile limitation)
	-s m n	  specify the dimensions of the image to be m by n
		  If only m is given, take n = m

#include <stdio.h>
#include <math.h>

#define N_POINTS 200

main()
{
    int i, j;
    double x, y;

    for (j = 0; j < N_POINTS; j++)
	for (i = 0; i < N_POINTS; i++) {
	    x = 2*i*M_PI/N_POINTS;
	    y = 2*j*M_PI/N_POINTS;
	    printf("%f ", 255*(1 + sin(x)*cos(y)));
	}
}

	data  |  make_image  -s 200  |  xv -