SciPlot Widget(3X)

NAME
SciPlot - a Widget to display scientific plots

OVERVIEW
The SciPlot Widget is a widget capable of plotting cartesian or polar graphs, including logarithmic axes in cartesian plots. The widget is subclassed directly from the Core widget class, which means that it does not depend upon any other widget set. It may be freely used with Athena, Motif, or the Open Look/Xview widget sets. (If the SciPlot widget is compiled with the flag "MOTIF" defined, the widget will be subclassed from XmPrimitive, allowing keyboard traversal of the widget. If "MOTIF" is not defined, the widget will still operate with Motif, but will not respond to events.)

FEATURES
Features provided in the widget include the following:

Cartesian or Polar plots
Automatic or manual axis scales
Logarithmic scales for cartesian plot
Degrees or radians for polar angles
Axis labeling
Legend drawing
Multiple lines per plot
Various symbols and line styles
Color support
User font selection
PostScript (EPS) output

USAGE
To use the SciPlot widget in an application, include the three source code files SciPlot.c, SciPlot.h, and SciPlotP.h with the rest of the source code for the application. Include the object SciPlot.o in the Makefile rule that compiles the application. If it is important for the widget to respond to Motif keyboard traversal or any events while in a Motif program, define the keyword "MOTIF" for the C compiler. In a Makefile, a commom place to put this definition is in a variable called "DEFINES". The line in the Makefile would look like this:

	DEFINES=-DMOTIF

In source code that uses the SciPlot widget, include the following two header files before references to the plot widget:

#include <X11/Intrinsic.h>
#include "SciPlot.h"

To create the SciPlot widget, use the following code as an example:

plotWidget=XtVaCreateManagedWidget("plot2",sciplotWidgetClass,parent,
		XtNheight, 250,
		XtNwidth, 250,
		XtNplotTitle, "Demo of Plot Widget",
		XtNxLabel, "X Axis (units)",
		XtNyLabel, "Y Axis (units)",
		XtNchartType, XtPOLAR,
		XtNdegrees, True,
		NULL);

This example creates a 250x250 polar plot widget as a child of parent, using degrees as the angle measurement unit. Data is plotted on the graph in groups called lists. Each list consists of a group of coordinates that will be connected together by a drawn line, and share the same point style, point color, line style, line color and legend label. Data is added to the widget using convenience functions only. There is no current provision to add data via the argument list. An example using one of the convenience functions is given below:

double rlist[]={14.,18.,22.,26.,30.,34.,38.,42.};
double tlist[]={30.,60.,90.,120.,150.,180.,270.,355.};
int line1;

line1=SciPlotListCreateFromDouble(plotWidget,
		8,rlist,tlist,"List 1");

The variable line1 is the identifier of the list that will be needed to modify the list by the other convenience functions that operate on lists. This example adds a list to be plotted in plotWidget. If plotWidget was created using the call to XtVaCreateManagedWidget above, the line would be added to a polar plot, where the angles in tlist would be interpreted as degrees. There are other convenience functions to specify colors and styles of the points and lines drawn in the Plot widget, as well as functions to pick the colors used and others to update previously defined lists. See the section "PUBLIC FUNCTIONS" below for descriptions of all of the convenience functions.

COLOR
The SciPlot widget fully supports color on displays which also support color. By default, two colors are allocated at creation time: black for the foreground, and white for the background. For the SciPlot widget to use any other color, one of the color convenience functions must be used to allocate a color in the global colormap. Colors are indicated by an integer returned from the color allocation convenience functions. The two default colors occupy the first two spaces in the color table, where the default background (white) is number 0, and the default foreground (black) is number 1.

FONTS
Fonts used by the SciPlot widget are referenced using special notation. This non-standard notation was used to be able to easily convert between PostScript and X11 notation, and as a result, only a subset of the fonts that are available in both X11 and PostScript are available. Fonts are referenced by using predefined keywords to indicate the typeface, style, and point size. Each keyword is an integer value defined in SciPlot.h, and a complete font definition is created by logically or-ing keywords together. Supported fonts and styles are listed below:

Font Name | Description
XtFONT_TIMES | Times
XtFONT_COURIER | Courier (monospaced font)
XtFONT_HELVETICA | Helvetica
XtFONT_LUCIDA | Lucida
XtFONT_LUCIDASANS | Lucida Sans Serif
XtFONT_NCSCHOOLBOOK | New Century Schoolbook

Style Name | Description
XtFONT_BOLD | Bold
XtFONT_ITALIC | Italic
XtFONT_BOLD_ITALIC | Bold and Italic

A font is specified by or-ing together these keywords, plus the size in points. Some examples follow:

12 point Times, bold:
	XtFONT_TIMES|XtFONT_BOLD|12

10 point Courier:
	XtFONT_COURIER|10

16 point Lucida, bold and italic:
	XtFONT_LUCIDA|XtFONT_BOLD_ITALIC|16

Note that XtFONT_BOLD_ITALIC is simply shorthand for XtFONT_BOLD|XtFONT_ITALIC

POINT STYLES
The SciPlot widget is capable of drawing markers at each data point. There are 19 predefined point marker definitions:

Style Name | Description
XtMARKER_NONE | no point marker drawn
XtMARKER_CIRCLE | open circle
XtMARKER_SQUARE | square
XtMARKER_UTRIANGLE | triangle (pointing up)
XtMARKER_DTRIANGLE | triangle (pointing down)
XtMARKER_LTRIANGLE | triangle (pointing left)
XtMARKER_RTRIANGLE | triangle (pointing right)
XtMARKER_DIAMOND | diamond
XtMARKER_HOURGLASS | hourglass shape
XtMARKER_BOWTIE | bowtie shape
XtMARKER_FCIRCLE | filled variants of the above...
XtMARKER_FSQUARE |
XtMARKER_FUTRIANGLE |
XtMARKER_FDTRIANGLE |
XtMARKER_FLTRIANGLE |
XtMARKER_FRTRIANGLE |
XtMARKER_FDIAMOND |
XtMARKER_FHOURGLASS |
XtMARKER_FBOWTIE |

LINE STYLES
For each list in the SciPlot widget, one of the following styles may be used to draw the lines that connect each point in the list:

Style Name | Description
XtLINE_NONE | no line (only points drawn)
XtLINE_SOLID | solid line (the default)
XtLINE_DOTTED | dotted line
XtLINE_WIDEDOT | widely spaced dotted line

POSTSCRIPT OUTPUT
Encapsulated PostScript (EPS) files of the plot displayed in the SciPlot widget may be generated. These files are suitable for printing or importing into documents that can handle the EPS format. Color is ignored when creating the EPS files, however.

NEW RESOURCES
Resources for the SciPlot widget are documented below, also showing the default values.

Name | Class | Type | Default
XtNaxisFont | XtCSciPlotFont | int | *1
XtNchartType | XtCMargin | int | XtCARTESIAN
XtNdegrees | XtCBoolean | Boolean | True
XtNdrawMajor | XtCBoolean | Boolean | True
XtNdrawMajorTics | XtCBoolean | Boolean | True
XtNdrawMinor | XtCBoolean | Boolean |  | True
XtNdrawMinorTics | XtCBoolean | Boolean | True
XtNlabelFont | XtCSciPlotFont | int | *2
XtNlegendLineSize | XtCMargin | int | 16
XtNlegendMargin | XtCMargin | int | 3
XtNmargin | XtCMargin | int | 5
XtNplotTitle | XtCString | String | "Plot"
XtNshowLegend | XtCBoolean | Boolean | True
XtNshowTitle | XtCBoolean | Boolean | True
XtNshowXLabel | XtCBoolean | Boolean | True
XtNshowYLabel | XtCBoolean | Boolean | True
XtNtitleFont | XtCSciPlotFont | int | *3
XtNtitleMargin | XtCMargin | int | 8
XtNxLabel | XtCString | String | "X Axis"
XtNyLabel | XtCString | String | "Y Axis"
XtNxLog | XtCBoolean | Boolean | False
XtNyLog | XtCBoolean | Boolean | False
XtNxOrigin | XtCBoolean | Boolean | False
XtNyOrigin | XtCBoolean | Boolean | False

Notes:
*1:	10 point Times
*2:	18 point Times
*3:	24 point Helvetica

XtNchartType
    Specifies a the type of chart to be drawn. Currently, two types are available: XtCARTESIAN = cartesian (X-Y) plot, XtPOLAR = polar plot.

XtNdegrees
    Sets the type of angular unit measurement: True=degrees, False=radians.

XtNdrawMajor
    Controls the display of major gridlines.

XtNdrawMajorTics
    Controls the display of major tic marks on the axes.

XtNdrawMinor
    Controls the display of minor gridlines.

XtNdrawMinorTics
    Controls the display of minor tic marks on the axes.

XtNlabelFont
    Names the font for use on the axis labels, as well as the numbers that mark the scale for each axis.

XtNlegendLineSize
    The length (in pixels) of the small lines used to show the line style and color in the legend box.

XtNlegendMargin
    Sets the border margin (in pixels) between the legend box outline and anything contained in it. Also controls the spacing between the line sample and the text, and the vertical spacing between legend entries.

XtNmargin
    The spacing (in pixels) of the plot with the border of the widget.

XtNplotTitle
    This is the title of the plot that is drawn along the lower border of the widget.

XtNshowLegend
    If True, the legend block is drawn.

XtNshowTitle
    If True, the plot title is drawn.

XtNshowXLabel
    If True, the X axis (or the polar axis) label is drawn.

XtNshowYLabel
    If True, the Y axis label is drawn.

XtNtitleFont
    This font is used for the title of the plot.

XtNtitleMargin
    Spacing (in pixels) between the plot and the title.
XtNxLabel
XtNyLabel
(Cartesian only.)
    Sets the label for each axis.

XtNxLog
XtNyLog
(Cartesian only.)
    Controls the logarithmic scales of the X and Y axes. If either of the resources is set to True, the corresponding axis will display in logarithmic units. Note that log axes cannot display numbers less than or equal to zero, so only points with values on that axis greater than zero will be plotted.

XtNxOrigin
XtNyOrigin
(Cartesian only.)
    If True, these resources force the origin of their respective axes to be included in the plot. If False, the displayed range only shows data between the minimum and maximum values along the named axis.

PUBLIC FUNCTIONS
The SciPlot widget uses an abstracted type "real" for its internal representation of floating point values. By default, it is typedeffed to float. Some of the convenience functions may depend on this real data type, but in general, separate functions will be provided depending upon a data type of float or double. Note that any changes to the widget are not reflected until a call to the public function SciPlotUpdate(). This includes any of the functions that add or remove lists, or change plot styles. Any changes accomplished through XtVaSetValues, however, automatically updates the widget.
int
SciPlotAllocNamedColor(w,name)
Widget w;
char *name;
    Attempts to allocate a color in the widget's colormap by using the standard X color name database.

    Returns a unique integer color ID greater than 1 if successful in allocating the named color. If unsuccessful, it returns a 1, which is the default foreground color black.
int
SciPlotAllocRGBColor(w,r,g,b)
Widget w;
int r,g,b;
    Tries to allocate the color named by the r, g, and b parameters. Note that these are integers ranging from 0 to 255, not 0 to 65535 as in X functions.

    As the previous function, it returns a number greater than 1 indicating that it found and allocated the new color. If it returns 1, it could not allocate the color, and returned the value for the default foreground.
void
SciPlotExportData(w,fd)
Widget w;
FILE *fd;
    Writes to the file (must already by opened) referenced by fd a summary of the state of the SciPlot widget. The columns of data are separated by tab characters, so with minor editing, the file generated should be importable by many commercial graphing programs.
int
SciPlotListCreateFromDouble(w,num,xlist,ylist,legend)
Widget w;
int num;
double *xlist,*ylist;
char *legend;
    Creates a list from the data given in the arrays xlist and ylist. Both arrays must have num entries. The parameter legend is the name of this list, and is drawn in the legend box. The initial colors (for both the points and the line) are set to black, the initial point style is set to a square, and the initial line style is solid.

    Returns an ID number for the newly created list. (Don't forget to call SciPlotUpdate().)
int
SciPlotListCreateFromFloat(w,num,xlist,ylist,legend)
Widget w;
int num;
float *xlist,*ylist;
char *legend;
    Same as SciPlotListCreateFromDouble, except takes arrays of type float.

    Returns an ID number for the newly created list. (Don't forget to call SciPlotUpdate().)
int
SciPlotListDelete(w,list_id)
Widget w;
int list_id;
    Deletes the list referenced by the ID number list_id. (Don't forget to call SciPlotUpdate().)
void
SciPlotListSetStyle(w,list_id,pcolor,pstyle,lcolor,lstyle)
Widget w;
int list_id;
int pstyle,pcolor,lstyle,lcolor;
    Sets the styles of the list with an ID number of list_id. See the sections COLOR, POINT STYLES and LINE_STYLES for descriptions of the available options. (Don't forget to call SciPlotUpdate().)
void
SciPlotListUpdateFromDouble(w,list_id,num,xlist,ylist)
Widget w;
int list_id,num;
double *xlist,*ylist;
    Replaces the data in the list referenced by list_id with the new data contained in the arrays xlist and ylist. Both xlist and ylist must be arrays of type double, and have num parameters. Note that the list to be updated may have been originally created with any of the creation convenience functions, not only with the functions that require type double. (Don't forget to call SciPlotUpdate().)
void
SciPlotListUpdateFromFloat(w,list_id,num,xlist,ylist)
Widget w;
int list_id,num;
float *xlist,*ylist;
    Same as SciPlotListUpdateFromDouble, but takes arrays of type float. (Don't forget to call SciPlotUpdate().)
void
SciPlotSetBackgroundColor(w,color)
Widget w;
int color;
    Sets the background color of the widget to the color specified. Note that the color ID number is obtained from one of the two functions SciPlotAllocNamedColor or SciPlotAllocRGBColor.
void
SciPlotSetForegroundColor(w,color)
Widget w;
int color;
    Sets the default foreground color to the color specified. (See the note about color IDs above.) This color is used as the default for the axis and legend box lines, as well as all of the text that appears in the widget. PostScript output remains in monochrome, however.
void
SciPlotSetXAutoScale(w)
Widget w;
(Cartesian only.)
    Forces the widget to automatically scale the X axis based on the minimum and maximum values determined from all of the lists. (Don't forget to call SciPlotUpdate().)
void
SciPlotSetXUserScale(w,min,max)
Widget w;
float min,max;
(Cartesian only, and not in logarithmic mode.)
    Forces the widget to display the X axis range based on the specified minimum and maximum values. (Don't forget to call SciPlotUpdate().)
void
SciPlotSetYAutoScale(w)
Widget w;
(Cartesian only.)
    Forces the widget to automatically scale the Y axis based on the minimum and maximum values determined from all of the lists. (Don't forget to call SciPlotUpdate().)
void
SciPlotSetYUserScale(w,min,max)
Widget w;
float min,max;
(Cartesian only, and not in logarithmic mode.)
    Forces the widget to display the Y axis range based on the specified minimum and maximum values. (Don't forget to call SciPlotUpdate().)
void
SciPlotUpdate(w)
Widget w;
    This function simply causes a recalculation of all internal parameters, and redraws the plot. Call this function after adding, deleting, or changing lists to force the Widget to redraw itself.
Boolean
SciPlotPSCreate(w,filename)
Widget w;
char *filename;
    This function generates an Encapsulated PostScript file of the current contents of the plot widget, sized to fit on an entire page. Colors are ignored, producing a PostScript file that is black and white only.

    The filename parameter should include the pathname, if required.

    Returns True indicating that the file was successfully created. Any error in file creation or in the subsequent writes to the file will cause the subroutine to return False.

NOTES
This code was developed on an IBM RS/6000 running AIX 3.2.4 and X11R5. It was also tested on two other machines: a DEC Alpha/AXP running OSF/1 3.0 with X11R5; and an SGI Indigo running IRIX 4.0.5 with X11R4. I have had reports versions running on HP-UX systems, but have not personally tested this widget on machines other those listed. The vertical text drawing routine is based on the "fill stippled" idea that I first saw in the code xvertext-5.0 by Alan Richardson (mppa3@syma.sussex.ac.uk). The first X11 plotting widget that I saw was the libXG package written by Sundar Narasimhan (sundar@ai.mit.edu). The libXG plotting widget Graph is based on a much more general widget called Display, which provides device independent 2D (and 3D) graphics. My attempts to change the Graph widget to do what I liked it to do led me to start from scratch and write this SciPlot widget. I didn't need (or want) to include the sort of functionality present in the Display widget, so I wrote the SciPlot widget as a self-contained widget that uses printer points as the basis of the graphics. Nevertheless, some of the techniques that I used are similar to those found in the Graph widget, so Sundar Narasimhan does deserve mention for the excellent libXG package.

BUGS
The font selection algorithm isn't as robust as it should be when trying to choose a replacement for a font; specifically, when the user requests a font or a size that doesn't exist in the X server.

SOURCE LOCATION
Source code for the SciPlot Widget is available in the archives of comp.sources.x, as well as via anonymous ftp on ftp.x.org in /contrib/widgets as SciPlot-?.?.tar.gz.

AUTHOR
Robert W. McMullen <rwmcm@orion.ae.utexas.edu> This widget is supplied as freeware, in the hope that it will be useful for developers in the X community. If you do use this widget, I do request that you include mention of the SciPlot widget in the documentation. Also, remember to include a copy of the entire copyright and permission notice! Thanks. Patches, improvements, suggestions, and bug reports are welcome at the above e-mail address. I will periodically post patches and improvements to ftp.x.org.

THANKS
Thanks to the following people for providing fixes and suggestions:
Todd Smith <mtsmith@vision1.engr.utk.edu>
Walter Underwood <wunder@msd.hpl.hp.com>
Michael Katzmann <michael%vk2bea@secondsource.com>
John Moyer <jrm@questconsult.com>
Mike Kienenberger <FXMLK@aurora.alaska.edu>

COPYRIGHT
Copyright (c) 1995 Robert W. McMullen Portions of the SciPlot Widget source code, as marked, are:
  Copyright (c) 1993 Alan Richardson (mppa3@syma.sussex.ac.uk)
Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. All work developed as a consequence of the use of this program should duly acknowledge such use. The author makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty. THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.