********************************************************************** * * README.XgPlot * * Copyright (c) 1992, John N. Sanders, Massachusetts Institute of * Technology, Lincoln Laboratory; 244 Wood Street, Lexington, * MA 02173. * All Rights Reserved. * Version 3.0 8/92. * ********************************************************************** To install this package, copy the XgPlot-x.x.tar.Z file to a directory named $(HOME)/XgPlot (other directories can be accomodated with a trivial change to the make file. Uncompress the file, un-tar it, and read INSTALL.XgPlot. See also CONTENTS.XgPlot: "cd" "mkdir XgPlot" "cd XgPlot" "uncompress XgPlot-x.x-tar-Z" "tar -xf XgPlot-x.x.tar" "more INSTALL.XgPlot" Notes on XgPlot package There are three main components to this package, the XgPlot x-y graphing routines, the XgMovie image display routines, and the Xg3d surface relief plotting routines. The first two are of fairly good quality and actively supported. The Xg3d is a much older version (a modification of an earlier x-y plotting routine) and has a number of limitations. Support for Xg3d is fairly limited. All three components run under X-Windows with the Motif toolkit. They are designed to be simple function calls from a parent program so they can be easily included in a number of applications. Several command line wrappers are included in the package to allow easy stand alone use of these tools as well as to provide examples of interfacing them to other programs. All of the components provide postscript output files. The XgPlot package is denoted with the prefix "Xg", the XgMovie package with the prefix "XgM", and the Xg3d package with the prefix "Xg3d". All functions and global variables are preceeded with these prefixes to aid in identification and minimize conflicts with other toolkits/packages. A simple program called memo reads text from a user specified file and displays an X-Windows banner. Invoke the program as "memo [ []]". The default font is Helvetica Bold, 36 point. The font should be the font file name, without the trailing .snf.Z suffix. XgPlot: ======= The XgPlot routine may be invoked from the command line with the pltxsh program (type "pltxsh -h" for a description of options). The XgPlot package supports linear, log, and probability scaling of axes, as well as division marker lines in the graph. It can plot up to 20 datasets on a single graph, and the graph may be saved to or loaded from an ascii graph description file. Postscript output is produced in the file "XgPlt.psc" which may then be sent to a postscript printer. A cursor is available to read out data point values (dataset, data point number, x, y). Independent left and right y-axes are supported and dataset may be assigned to either. XgMovie: ======== The XgMovie package comes in two flavors. XgMovie loads an entire set of frames into memory, and then plays the images back as a movie loop. This requires enough memory for both the entire raw dataset and the Pixmaps of each image stored in the X-server. By doing this, disk access is eliminated from the movie loop, thereby allowing much faster playback. However, each time an operation such as zoom or scaling is invoked, the entire dataset must be remapped. The second flavor is XgMovieF which reads and displays a frame at a time. This allows the use of arbitrary size files, and greatly reduces the time required to execute a zoom or scale, because only one frame is kept in memory. The penalty is that playback is much slower, limited primarily be disk access times. The two versions may be invoked from the command line with xgm or xgmf, respectively. XgMovie is independent of the image file format, since the image is read into memory by the calling program (e.g. xgm) and just passed a pointer to the data in memory. However, XgMovieF must read the data from disk. The I/O routines have been localized to one function for easy change. The image file format used is referred to as the ETS format and is described in etsheadr.h. The actual I/O function is in filefunc.c, with an interface routine in XgMovieF.c The XgMovie (& XgMovieF) package allow linear, logarithmic, square root, and histogram equalization scaling of the image, as well as adjusting the grey scale ramp. The images may be zoomed by factors of 1, 2, 4, and 8 times, and may be flipped in the vertical direction. The movie loop may be played forward or reverse, at .1, .2, .5, and 1 second per frame, or the movie may be turned off. If the movie is off, a stationary image is displayed, but the user may move a slider to select a different image in the sequence, or single step through the images. It is possible to produce x-y plots of row profiles, column profiles, or an image histogram. It is also possible to select a sub- region of the image and produce an independent movie loop of that region. Both versions produce a postscript output file, "XgMov.psc". Xg3d: ===== The Xg3d package may be invoked from the command line with either plt3d or slc3d. The Xg3d package produces a wire mesh surface relief plot of an image. The 3d package uses the same ETS format as the XgMovie package. Plt3d has 2 command line options (in addition to the data file name and the Xtoolkit options). These are -f n where n is the number of the frame in the data set to display. For example, if the data set contains 16 frames of two dimensional data, the default is to display the first frame. By entering -f 8 we could display the eighth frame. The second option is -s x where x is a scaling factor. The 3-dimensional display requires a scaling factor for projecting the data. The default is 0.1 which works well with the sample data file provided. However, different scaling factors may be appropriate for different data sets, so instead of having to change the value from a menu everytime the program is run, the command line option is available. Slc3d is a variation of plt3d. It allows one to plot a planar slice from a three dimensional data set. The default is to plot the plane defined by row row 1 (frame and column vary). The -f option allows the selection of a different row. The -c option plots a plane defined by column 1 instead of row 1. The -t option transposes the axes. Sample Data: ============ Four sample data files are included. Plot.dat and gauss.dat are x-y data for use with pltxsh (pltxsh plot.dat). Gauss128.dat is surface data for use with plt3d (plt3d gauss128.dat). The file movie.dat is a 16 frame sequence of 128x128 pixel images, primarily for use with XgMovie. Plot.dat and gauss.dat are all ascii and may be printed out. gauss128.dat and movie.dat are not. They are described in etsheadr.h. Known Bugs: There is no graceful way to recover from an error in a graph description file, and thus the program crashes. Similarly, when adding/changing data sets, there is not sufficient error checking to ascertain whether the data is valid. (missing primarily due to laziness) XgPlot can plot multiple data sets. Xg3d can only plot one surface at a time. The ability to plot multiple (overlaid) surfaces would be nice. (moderate effort) Contact: jns@ll.mit.edu Jack Sanders MIT Lincoln Laboratory 244 Wood Street Lexington, MA 02173 617-981-0719