**************************************************************************
FPLOT
Version 2.35
January 30, 2000
Michael C. Ring
ringx004@tc.umn.edu
Latest release will be available at
http://tc.umn.edu/~ringx004
**************************************************************************
* *
* Copyright (C) 1997 - 2000 Michael C. Ring *
* *
* This software is Freeware. *
* *
* Permission to use, copy, and distribute this software and its *
* documentation for any purpose with or without fee is hereby granted, *
* provided that the above copyright notice appear in all copies and *
* that both that copyright notice and this permission notice appear *
* in supporting documentation. *
* *
* Permission to modify the software is granted, but not the right to *
* distribute the modified code. Modifications are to be distributed *
* as patches to released version. *
* *
* This software is provided "as is" without express or implied warranty. *
**************************************************************************
The files created during extraction are as follows :
FILE DESC
--------------------------------------------
README This file.
README.PS This file in Postscript format
HISTORY.TXT Brief history of the program
FPLOT.H ----+
GLOB.H +-- Header files
PROTO.H ----+
FPLOT.C ----+
FPCMD.C |
FPSET.C +-- C Source Files
FPOUT.C |
FPLIB.C ----+
FPLOT.EXE MS-DOS Executable
MULTIPLT.C C Source File
MULTIPLT.EXE MS-DOS Executable
MKDOS.BAT Build batch file for DOS using Microsoft C
MKDOSGCC.BAT Build batch file for DOS using GCC
MKUNIX Build script for generic Unix
FPLOT.1 ----+
FPLOT-1.PS +-- Unix man pages with postscript versions
MULTIPLT.1 |
MULTI-1.PS ----+
CMD.ALL Sample command file, *ALL* options listed here
CMD.2 ----+
CMD.3 |
CMD.4 +-- Sample command files
CMD.5 |
CMD.6 ----+
DATA.1 ----+
DATA.2 |
DATA.3 +-- Sample data files
DATA.4 |
DATA.5 |
DATA.6 ----+
**************************************************************************
TABLE OF CONTENTS
-------------------
1 Introduction
1.1 Program Installation
2 Running the Samples
3 FPLOT Parsing Rules
4 Commands (Reset, Set, Data, Plot)
5 Data File Format
6 Line Styles and Symbols used
7 Points of Interest
8 MULTIPLT
9 Closing
**************************************************************************
1 INTRODUCTION
Why was this program written? This is a good question since there
are many plotting programs available. GNUPLOT is actually one I
use very frequently. It is very powerful and it can plot practically
anything you throw at it. It supports numerous printers and terminal
types also. If you really want a super powerful plotting program,
GNUPLOT is it. However, GNUPLOT doesn't do two things which I
like/need:
1) You can't go directly from ASCII data to a plot on the command
line. You can load a command file :
gnuplot loadfile
where loadfile is an ASCII file containing a list of commands
and the last line in this command file might be
plot "datafile"
But as far as I know, you can't directly go from "datafile"
to a plot file. FPLOT can do this.
For DOS :
program_that_outputs_ascii_data | fplot -r -- > LPT1
For UNIX :
program_that_outputs_ascii_data | fplot -r -- | lp -dprinter
The arguments used in fplot will be described later in this file.
2) I sometimes need to plot many, many data points (> 100,000)
This usually isn't a problem under UNIX, but I use DOS sometimes
and the DOS version of GNUPLOT simply runs out of RAM with
this many data points. Actually on my DOS system, GNUPLOT can
only plot 2700-3000 data points. FPLOT can read any number of
data points since it doesn't store the data samples in RAM,
it simply re-reads the data file if it needs to. This obviously
takes longer but there are no limitations. One of my test files
contained 1,000,000 data points. It took 15 minutes to create
the postscript file and another 8 to get a printout, but it
did it under DOS.
As of now, FPLOT only supports postscript printers. I have hooks in
the code to support other printers, namely Epson FX/LQ and HPGL. If
there is sufficient demand for other printers, I will add them at a
later time.
The program is only about 5000 lines of C code and it has been
tested under MS-DOS, HP-UX, Sun, and Linux systems. These are the
systems I have access to. If anyone ports this to another OS,
please send me the build file and any changes that were needed to
the source code. There will not be any Windows versions since this
is, inherently, a command line utility program. The C code is
really quite ordinary, I think it should port to other OS's
without too much difficulty.
Even though I have been writing C code for many years, this is my
first attempt at postscript code. Drawing graphs is actually a
simple process. All you are really doing is drawing short line
segments together with some text added for the title, axis labels,
etc. I found Peter J. Weingartner's "A First Guide to Postscript"
on the net. I used his document and samples from gnuplot and
other postscript programs to generate my postscript code. I have a
feeling some of the postscript code may not be as efficient/clear
as it could be, but it does work. I did not use any operators that
were not in Peter's document since I wanted to guarantee that all
the postscript code met Adobe's 1.0 spec. This would enable my
program to work even with 'older' printers. I will welcome any
input that makes the postscript code cleaner and/or more efficient.
I chose postscript output for three reasons. 1) My workplace and my
home have postscript printers, 2) Since postscript is straight
ASCII, it works really nice in pipes, and 3) It is fairly easy to
post-process postscript output to put multiple plots on one sheet of
paper.
The program 'multiplt' will put multiple plots (up to 9!) on 1 page.
As an added bonus, multiplt will also work with GNUPLOT (assuming
postscript output) files as well as FPLOT. See section 8 for more
details.
I will attempt to distribute FPLOT under 2 file names. Both archives
will contain the exact same files, except that they will have the
correct end-of-line terminator for the ASCII files. The DOS archive
will be named fplot$$$.zip and the Unix archive will be named
fplot-$.$$.tar.gz where $$$ will be an indicator of the program
version. The latest version of FPLOT will be available on my
(very plain) web page. See location at the top.
The file 'history.txt' will detail the updates made for each
release. The new features are listed there as well as what version
the features appeared in.
FPLOT can plot an infinite number of Y ranges. The latest feature
of the program allows a 'line break' in the data. If a blank line
(or just a comment line) is found in the data, the current line
segment is completed and then a new line segment will be
generated starting with the first data line after the line break.
By using multiple line breaks, any number of Y ranges can be plotted.
1.1 PROGRAM INSTALLATION
DOS : Simply copy FPLOT.EXE and MULTIPLT.EXE to somewhere in your
path. It is now ready. The programs were built with Microsoft C
8.00c. You can re-build FPLOT and MULTIPLT by running the batch
file 'mkdos'. It also can be built by MSC 5.1 but you will need
to delete the /Oce arguments. MSC 5.1 does not understand these
optimization flags. I do not have access to MSC 6 or 7 so I'm
not sure what the commands would be, though I think they would
be quite similiar.
If you have GCC for DOS, the batch file 'mkdosgcc' will build
FPLOT and MULTIPLT. If you would like 32 bit versions of the
programs (as built by GCC), let me know and I can send them
to you.
UNIX: Run the mkunix script. This should work for most unix systems.
It works on HP-UX, Sun, and Linux. I assumed the compiler will
be GCC. If you do not have gcc on your system, substitute the
correct name to invoke your compiler, probably 'cc'. These
scripts will build 'fplot' and 'multiplt'.
After the programs are built, copy them to somewhere in your
path. /usr/local/bin is usually a good one since everyone
can use it there, but usually only the root user has write
privleges in that directory.
**************************************************************************
2 RUNNING THE SAMPLES
See section 3 for the parsing rules and section 4 for
the 'set' commands.
Command Commentary
------- ----------
(1)
fplot -r data.1 >output.ps The -r option tells fplot that we are
processing a raw data file and not a
command file. The postscript output
will be redirected to 'output.ps'
(2)
DOS:
fplot -r data.2 > LPT1 Send plot directly to printer on LPT1
UNIX:
fplot -r data.2 | lp -dprinter Send plot to printer named 'printer'
(3)
DOS:
type data.2 | fplot -r -- >LPT1 The -- filename tells fplot to take
input from stdin instead of a file.
The -- argument must be the last one
on the fplot command line.
UNIX:
cat data.2 | fplot -r -- | lp[r]
(4)
DOS:
fplot cmd.2 > LPT1 Read in command file 'cmd.2', generate
fplot cmd.3 > LPT1 the plot and send it to LPT1. Ditto
fplot cmd.4 > LPT1 for command file 'cmd.3', 'cmd.4',
fplot cmd.6 > LPT1 and 'cmd.6'.
UNIX:
fplot cmd.2 | lp -dprinter
fplot cmd.3 | lp
fplot cmd.4 | lp
fplot cmd.6 | lp
(5)
DOS:
type cmd.5 | fplot -- > LPT1 Take in command file 'cmd.5' from
stdin and send the plot to LPT1.
UNIX:
cat cmd.5 | fplot -- | lp
(6)
DOS:
type cmd.all | fplot -- > LPT1 Take in command file 'cmd.all' from
stdin and send the plot to LPT1. Also
UNIX: shows how to embed data in the command
cat cmd.all | fplot -- | lp file.
FPLOT assumes you want to process a 'command' file. The -r command
line option is used to process a RAW data file. This file just has
the numbers you want to plot in it. A filename of '--' will process
stdin instead of a file.
**************************************************************************
3 FPLOT PARSING RULES
FPLOT parses the data files and command files into 'fields.' The
term 'fields' means that FPLOT will split an input line into
'obvious' fields or columns of data.
1) The delimiters for FPLOT are spaces, commas, and tabs.
2) Any text within double quotes will be treated as one field.
2A) Any text WITHOUT double quotes will be treated as individual
fields, each 'word' is one field.
3) A field beginning with a '#' will be treated as a comment.
4) Any text after a '#' on the line will be treated as a comment.
Examples : FPLOT finds :
7.4, 9.1, -12.0e+7 3 fields
0.2, "text in field 2", QQ 3 fields
0.2, bad text in field 2, QQ 7 fields (see 2A)
3.321E-8 5.6709 -12.765 0 0.43 5 fields
3.321E-8 5.6709 -12.765 C 0.43 5 fields
3.321E-8,5.6709,-12.765,C,0.43 5 fields
set papersize 8.5,11 # adjust papersize 4 fields
set title "GRAPH TITLE" #comments after a '#' 3 fields
#only a comment here 0 fields
**************************************************************************
4 COMMANDS (RESET, PLOT, DATA, SET)
o) The sample file 'cmd.all' has every supported command in it. You
can use this as a template for creating new command files.
o) Blank lines and lines beginning with a '#' are comment lines. Any
text after a '#' on a line is considered a comment also.
o) Commands may be in uppercase or lowercase.
o) Keywords shall be separated by 1 or more spaces, tabs, or commas.
o) Any text entries should be in double quotes :
set xlabel "Frequency (KHz)"
set title "This is the Graph's Title"
o) Since the program can plot two Y-ranges independently, specifying
Y commands are either:
set y1... or set y1multiplier 2.0
set y1label "Velocity (mph)"
set y2... set y2range autorange
set y2offset -3.5
The '1' is optional for all set y1... commands. The examples
above could be
set ymultiplier 2.0
set ylabel "Velocity (mph)"
If you are only plotting 1 Y range, leaving the '1' off of
set commands will probably be more clear. However, if you
are plotting 2 Y ranges, having the '1' will probably help.
Choose whichever makes more sense to you.
Note that when plotting more than 2 Y-ranges, Y ranges 1 and
3-N will use the parameters as specified for the Y1 range.
The Y2 range will use the parameters as specified for the Y2
range. The only exception is that if 3 or more ranges are being
plotted, the Y2 range will be forced to be the same as the other
Y ranges.
----------------------------------------------------------------------------
reset defaults This is the only allowed reset command. It can
be used to reset to a known state. It will
typically be used between many plots in the
same command file. Example :
reset defaults
set ...
set ...
set ...
set outputfile "data1.ps"
plot "datafile.1"
#
#
reset defaults # known start-up state
set ...
set ...
set ...
set outputfile "data2.ps"
plot "datafile.2"
#
#
reset defaults # known start-up state
set ...
set ...
set ...
set outputfile "data3.ps"
plot "datafile.3"
#
----------------------------------------------------------------------------
plot "filename" Plot the data in 'filename' using the rules from
plot "/tmp/filename" previous 'set' commands.
plot "C:\data\filename"
----------------------------------------------------------------------------
The 'data' command allows you to embed your data
in the command file. Put the data between the
commands 'data start' and 'data stop'. When
data stop ===OR=== end of file is found, the
plot will be generated.
'data stop' is only necessary if you want to
continue with additional plots in the same
command file. Line breaks may be used here also
to achieve more Y ranges. See section 5, Data
File Format.
set ...
set ...
set ...
data start
3.2 1.2 5.3 9.3
3.32 0.9 4.7 11.2
3.4 -0.2 3.2 12.9
# line break here
3.53 -2.8 2.52 13.4
3.6 -4.7 7.3E-1 17.3
3.717 -7.36 -2.73 19.2
3.8 -9.1 -4.21 23.04
data stop
----------------------------------------------------------------------------
NOTE : The following 'SET' command are in alphabetical order, except for
the commands that are related.
----------------------------------------------------------------------------
set coordinates label001 inches This command specifies the
label2 plotcoordinates coordinate system used to position
label128 inches the 128 labels. 'inches' will use
the physical dimensions of the page
labelall inches to specify label placement.
'plotcoordinates' will position the
labels in the graph's coordinate
system. See the 'set label' command
below. Use 'labelall' to set all
128 at once. The default coordinate
system is 'inches'.
----------------------------------------------------------------------------
set fielddefinition x,6 Tells fplot which fields contain the data.
set fielddefinition y,8 (y and y1 are synonyms). The example here :
set fielddefinition y1,8
set fielddefinition y2,0 Field 6 will contain the X axis data
Field 8 will contain the Y axis data
We will not be plotting a Y2 range (== 0)
set fielddefinition ##,0 y1 through y12 may be substituted for '##'.
This allows the fields for all 12 Y ranges
to be specified.
The defaults are all 0.
If they are ALL 0, fplot will determine how
to plot the data based on the following :
1 field of data found, Plot a single Y range
2 fields , Plot an X,Y data pair
3 fields , Field 1 is X data, Fields 2,3 are Y1,Y2.
4 fields , Field 1 is X data, Fields 2,3,4 are Y1,Y2,Y3.
5 fields , Field 1 is X data, Fields 2,3,4,5 are
Y1,Y2,Y3,Y4.
etc.
If you have 2 fields of data and you want to
plot 2 Y ranges and have X be the number of
samples in the file (the default would be an
X,Y data pair), do :
set fielddefinition x,0
set fielddefinition y1,1
set fielddefinition y2,2
Specifying any 'fielddefinition' to non-zero
will tell fplot to bypass the routine to
determine how to plot the data. fplot assumes
you have specified exactly which fields are
used and how you want them used.
If 13 fields are found, field 1 will be the
X data and fields 2-13 will be the data for
the 12 Y ranges.
If 14 or more fields are found, fields >= 14
will be ignored and fplot will treat the file
as if 13 fields were found.
----------------------------------------------------------------------------
Specify the font size for each label.
set fontsize title 14.0 Floating point is allowed! (i.e. 12.75)
xlabel 14.0
ylabel 14.0 The 4 major labels default to 14 point.
y1label 14.0 y & y1 are the same.
y2label 14.0
set fontsize label1 10.0 Floating point is allowed!
label$$$ 10.0 '$$$' may be 1-128.
label128 10.0 These 128 labels default to 10 point.
labelall 8.5 Set ALL 128 at once.
----------------------------------------------------------------------------
set graphborders .5 1.3 .8 2 Left, Top, Right, Bottom in inches
1 1 1 1 The default is 1 inch borders on all 4 sides.
----------------------------------------------------------------------------
set graphtype points There are 3 styles to choose from. Draw just
linesandpoints 'points', just 'lines' or both. The default
lines is 'lines'.
----------------------------------------------------------------------------
set gridlines off Turn the grid lines on, off, or have a small
ticks tick mark near the numbers. The default is
on on.
----------------------------------------------------------------------------
There are 128 labels you can position anywhere on the page.
IF 'INCHES' IS THE COORDINATE SYSTEM: (see above)
The first number (X position) is horizontal inches from the left
edge of the page. The second number (Y position) is vertical inches
from the bottom of the page.
'center' may be used to center the label in the middle of the page.
'rightjustify' may be used to place the label against the right
hand edge of the plot, allowing for 0.5 inches from the edge of
the page. 'center' and 'rightjustify' assume a 0 deg rotation for
the label.
Note that 'leftjustify' is not needed since a simple constant will
suffice, i.e. 0.5 inches.
IF 'PLOTCOORDINATES' IS THE COORDINATE SYSTEM: (see above)
The first number is scaled to the 'X' axis scaling of the plot
being generated.
The second number is scaled to the 'Y' axis scaling of the plot
being generated. The first Y range (y1range) is used for the
label Y coordinates.
The defaults are all labels off.
set label10 rightjustify, 8.20, "M. Ring 9-30-99"
set label53 2.7, 5.4, "Extra label 53 at 2.7, 5.4"
set label96 1.7, 2.4, "Extra label 96 at 1.7, 2.4"
set label71 center, 4.4, "Extra label 71 horizontally centered"
set label113 rightjustify, 1.6, "Right Justify Extra label 113"
set label$$$ 2, 3, "label text" # '$$$' may be from 1-128
----------------------------------------------------------------------------
set outputfile "data.ps" Specify the output file name. The default
is stdout.
----------------------------------------------------------------------------
set outputformat hpgl2 Only postscript is supported now. Specifying
set outputformat epsonlq the others will terminate fplot with an error
set outputformat epsonfx message.
set outputformat postscript
----------------------------------------------------------------------------
set papersize 8.5, 11.0 Set the width and length in inches. 8.5x11
is the default.
----------------------------------------------------------------------------
set pointsizescale 0.85 Set the relative size of the 'points' when
plotting 'points' or 'linesandpoints'.
< 1.0 = smaller
> 1.0 = larger
1.0 = default
This command is useful when plotting many,
many data points in a scatter plot.
----------------------------------------------------------------------------
Specify the rotation angle for each label.
set rotation label1 0.0 Rotate each label by the number of degrees
set rotate label2 -90 specified. The rotation may be from -180 to 180
label$$$ 10.0 '$$$' may be 1-128.
label128 22.1 These 128 labels default to zero degrees.
labelall 90.0 Set ALL 128 at once.
A positive rotation is counter-clockwise.
A negative rotation is clockwise.
----------------------------------------------------------------------------
set skipfactor 50 Plot every 51st data point (plot 1, skip 50,
plot 1, skip 50, etc.)
The default is 0, don't skip any points.
----------------------------------------------------------------------------
set title "=== Graph Title ==="
set xlabel "+++ X Axis Label +++"
set ylabel "Y Axis Label"
set y1label "Y1 Axis Label"
set y2label "((( Y2 Axis Label )))"
These 4 labels are used to label the title and each of the axis's
as desired.
The defaults for these 4 labels are off.
----------------------------------------------------------------------------
set usesamples 100, 200 If you have a data file with many, many points
in it, but you only care about samples 100
through 200, you can specify to only use this
small range.
The default is to use all the data points.
Note: these numbers are not tied to the X
axis scale, i.e. they are not when X=100
to X=200. They are LINES 100-200 in the
data file.
----------------------------------------------------------------------------
set xaxisscale log Set X axis to be linear or log scale.
set xaxisscale linear The default is linear.
----------------------------------------------------------------------------
set xmultiplier 1.0 Rescale any axis as desired.
set ymultiplier 1.0
set y1multiplier 1.0 The default multipliers are 1.0.
set y2multiplier 1.0
set xoffset 0.0 The default offsets are 0.0.
set yoffset 0.0
set y1offset 0.0
set y2offset 0.0
This can be used to re-scale some input data as follows :
plotted-data = data-file-data * multiplier + offset.
For example, let's assume we want to plot the national debt vs.
years and our data file looks like : (these numbers are completely
imaginary and are for demonstration purposes only!)
1900 7.80E+8
1910 8.42E+8
1920 9.72E+8
1930 1.03E+9
1940 2.33E+9
1950 4.09E+9
1960 5.82E+9
1970 6.17E+9
1980 8.49E+9
1990 1.16E+10
and our Y-label is
set ylabel "National Debt in Dollars"
We could be more friendly by doing :
set ymultiplier 1.0E-9
set ylabel "National Debt in Billions of Dollars"
Another example : Our data file has 1 field of data :
5.02 ----+
5.01 |
5.04 |
. | total of 200 data points
. |
. |
5.17 ----+
Our X axis labels will be in data samples, 1-200. Let's assume we
know that these 200 samples were in fact time period 10.0 seconds
to 11.0 seconds. We want our X axis to display 10-11 seconds, not
samples 1-200.
set xmultiplier 0.005 # (11 - 10) / 200
set xoffset 10.0
set xlabel "Time (seconds)"
----------------------------------------------------------------------------
set xrange -10 -3 Specify the range you want for each axis
set yrange -100, -90
set y1range 1.0E+3, 2.0E+3
set y2range -10 30
set xrange autorange Autoranging is the default for all axis's.
set yrange autorange
set y1range autorange
set y2range autorange
set y2range y1range Force Y2 and Y1 to have the same scaling. The
default is for Y1 and Y2 to have independent
scaling when 2 Y ranges are being plotted.
This command is implied if 3 or more Y ranges
are being plotted.
----------------------------------------------------------------------------
**************************************************************************
5 DATA FILE FORMAT
The format of a data file is simply ASCII text. It will be
parsed the same as the 'commands' from above. The data can
be delimited with spaces, tabs, or commas. The data file
should have the data on successive lines.
FPLOT now supports a new feature in data file format. A blank
line (or just a comment line) in the data stream is now interpreted
to indicate a 'line break'. The current line segment is completed
and then a new line segment will be generated starting with the
first line after the line break. This is useful for (1) drawing
maps and (2) it gives the user an (effective) infinite number of
possible Y ranges.
Only 1 line at a time is allowed for a line break. If there are 2
or more successive blank lines, FPLOT will terminate with an error.
Also, the first line in a data file must have data, the first line
is not treated as a line break.
See the sample data files, "DATA.*"
NOTE : The 'line break' feature also works with the old method
of specifying Y ranges (using multiple fields of data).
Example: data file has 6 fields, so field 1 defaults to the
X axis and fields 2-6 defaults to 5 Y ranges. If the data file
has line breaks, such as:
2 42 55 -71 92 -32
3 37 65 -62 98 -37
4 25 72 -87 84 -42
5 18 62 -68 82 -39
# line break 1 (could have been an empty line also)
1 85 82 -77 11 -92
2 28 32 -58 32 -86
# line break 2
3 85 82 -71 71 -61
5 28 32 -54 62 -46
This data file would result in 15 line segments. There
are 3 unique data sections (due to 2 line breaks) times
5 y-ranges = 15 total y ranges.
The most useful and flexible use of line breaks is to
simply have one X,Y pair on a line. Then use multiple
line breaks to get as many Y ranges as you need.
**************************************************************************
6 LINE STYLES and SYMBOLS used
FPLOT uses a combination of varying line widths and black/gray
color to differentiate between different Y ranges when only 'lines'
are being drawn. It also uses different symbols when 'points' or
'linesandpoints' are being drawn. The various combinations are
shown below.
If 'linesandpoints' is the graphtype, then medium-width black lines
will only be used since the symbols can be used to differentiate
between the Y ranges.
Y-Range Line-width Line-color Symbol
-----------------------------------------------------------------
1 Medium Black Diamond
2 Narrow Black Box
3 Wide Black Triangle Up
4 Medium Gray Triangle Down
5 Narrow Gray Plus sign (+)
6 Wide Gray Cross sign (X)
The pattern is repeated for Y ranges 7-12.
**************************************************************************
7 POINTS OF INTEREST
o) The version of the distribution package is now tied to
the RCS version of fplot.c. fplot will automatically parse
the version from RCS_ID[]. This is why there was an abrupt
change in the version from 0.6b to 2.10.
o) The program will parse numbers in 'normal' or scientific
notation. It can handle 3691.9275 as well as -9.87364e-10.
The exponent 'e' may be upper or lower case. I just use
the 'atof' function in C.
o) The program needs to have some idea of what 'zero' is. In
real life floating point calculations, you can never safely
check for equality (or inequality) between two numbers. You
have to subtract them and compare the result against a
sufficiently small value. The small value I chose was 1.0E-12.
Any number smaller than this will be treated as zero. If you
need to plot numbers smaller than this, I suggest using the
'set [x|y]multiplier NN' command. An example of this is shown
above.
o) The program creates temp files during execution and deletes
them at the end.
For DOS, the files will be in the directory pointed to by the
TMP environment variable or in C:\ if TMP is not set.
For Unix, the files will be /tmp/fpl#####.### where the # will
be uniquely set. On some systems, '/usr/tmp' may be a better
choice, depending on the amount of free disk space in each
directory.
o) The program has a fairly strict parser. Any command it can't
make sense of will terminate the program with some appropriate
error message.
o) All global variables begin with 'g_'. This convention is
something I've done for a long time. It is very handy when
working on a program you haven't seen for a long time.
(Maintenance Mode!).
o) I've used wrapper functions around malloc and free. I allocate
extra bytes and put a signature pattern before and after the
block and verify the pattern before the 'free'. This guarantees
that you haven't overrun a memory block or free a block that
you've already freed. A fairly simple program like this probably
doesn't need them but I already had them lying around.
o) There are a bunch of hard coded constants in the postscript
code that I'm not proud of. They should be #defines or
variables with a descriptive name.
o) There is a font size lookup table in the code. This table is
not exact. I need to know the size of each character so I can
center the 4 main labels on the graph; the title, x axis label,
and both y axis labels. I could not find any postscript operator
in Peter Weingartner's document that resembled the length of
a string given the string and the font with the current point
size. So what I did (don't laugh) was print out each ASCII char
50 times and measured the length of each char with a ruler,
converted the length to my coordinate system and I'm done.
These are the numbers in the table. If anyone has the point size
for the 95 printable ASCII char, please send them to me and
I will put the real numbers in the table, or supply some
postscript code that does the auto-centering for me.
Even though this is not as scientific as I like, the net result
is actually quite good.
o) The program captures a handful of 'signals.' This is done so
I can always clean up after myself, releasing memory and
deleting the temp files I create. If any other OS's require
more/less signal capturing, please let me know. As of now
I just control this with conditional compiles in the code.
**************************************************************************
8 MULTIPLT
MULTIPLT can be used to post-process the postscript output from
FPLOT. It will also work with GNUPLOT. It should work with any
postscript file if it meets the following 2 conditions:
a) The original postscript file results in 1 page being
printed.
b) The original postscript file uses the 'showpage' command
to eject the page near the end of the file. 'showpage'
must be the only command OR the first command on the
line where it is found.
Up to 9 plots can be output on 1 physical page using multiplt.
There will be a unique output for 2, 3, 4, 6, 8, and 9 plots.
5 plots will be output in the same format as 6 plots with the
last plot being blank. 7 plots will be output in the same
format as 8 plots with the last plot being blank.
MULTIPLT accepts '--' as a filename. This will output an empty
plot for that position on the plotted output. This can be used
to force multiplt to output the plot in a different format,
i.e. force a 6 plot format with a 4 plot input by using '--'
two times :
multiplt f1 f2 -- -- f3 f4 >output [4 plots on the page with ]
[the 2 middle 'plots' blank]
MULTIPLT supports 8 different output page sizes. The 8 page sizes
are :
'letter' 8.5 x 11 inches (default)
'legal' 8.5 x 14
'tabloid' 11 x 17
'a3' 297mm x 420mm
'a4' 210mm x 297mm
'a5' 148mm x 210mm
'b4' 257mm x 364mm
'b5' 182mm x 257mm
The page size is specified by calling multiplt with '-s' as the
first argument. The default is letter, 8.5 x 11. Examples :
multiplt -sa4 f1 f2 ... output page size is A4
multiplt -slegal f1 f2 ... output page size is LEGAL, 8.5 x 14
multiplt -sb5 f1 f2 ... output page size is B5
If the input files were created with 'fplot', the input files may
be set to any arbitrary page size. 'fplot' outputs a special comment
in the postscript header indicating the page size which multiplt
uses to re-scale the data, if necessary.
If the input files were created with 'gnuplot', the input files must
be scaled using 8.5 x 11 inches. The output page size may still be
changed but the input page must be 8.5 x 11.
MULTIPLT simply reads postscript files from the command line,
reformats the output, and sends the data to stdout. You can
redirect the output to another file if so desired.
Assume we have 9 postscript files from FPLOT or GNUPLOT named
f1.ps through f9.ps.
multiplt f1.ps > LPT1 (DOS) [Doesn't really do anything since]
multiplt f1.ps | lp (Unix) [only 1 file is specified. ]
multiplt f1.ps > newfile.ps [Included for symmetry. ]
multiplt -sa4 f1.ps > newfile.ps [With '-s', easy way to translate]
[from one page size to another! ]
multiplt f1.ps f2.ps > LPT1 Put 2 plots on 1 page.
multiplt -sa4 f1.ps f2.ps f3.ps > LPT1 Put 3 plots on 1 A4 page.
multiplt -slegal f1.ps f2.ps f3.ps f4.ps > LPT1 Put 4 plots on 1 8.5x14 page.
etc ...
multiplt f1.ps ... 2-8 ... f9.ps > LPT1 Put 9 plots on 1 page.
NOTE! : multiplt can be used recursively. In other words, the
input to multiplt can be previous outputs of multiplt.
This can be used to put 12, 16, 18, 24, ... plots on a
page. As an example, this is how to put 16 plots on
a page :
multiplt f1 f2 f3 f4 > f1tmp Put 4 plots on 1 'page'.
multiplt f5 f6 f7 f8 > f2tmp Put 4 plots on 1 'page'.
multiplt fa fb fc fd > f3tmp Put 4 plots on 1 'page'.
multiplt fe ff fg fh > f4tmp Put 4 plots on 1 'page'.
multiplt f1tmp f2tmp f3tmp f4tmp > LPT1 Put all 16 plots on 1 'page'.
**************************************************************************
9 CLOSING
If you have any questions, problems, or would like additional
features, (like new set commands) feel free to contact :
Michael Ring
10750 108th Ave. N.
Maple Grove, MN 55369
e-mail : ringx004@tc.umn.edu
web : http://tc.umn.edu/~ringx004
**************************************************************************
