WHAT IS BARPLOT?
----------------
Barplot is a program that takes as input a scripted language that describes
progress along various points of a continuum. The output is scaled to the
user's specification. Additionally, barplot can calculate percentage of
reported progress to an internal default accuracy of 1:10000
Barplot can output .JPG files, and does so to a file or to stdout. It is
possible to have barplot generate these .JPG images "on the fly" with a
simple .CGI or other Server-side process on a webserver. We use this
constantly at Gulf Interstate Engineering to model real-world progress of
various activities in near real-time.
This version of barplot is 1.0.00907.00
The latest version can be found at http:\\www.gie-mis.com\barplot
WHAT ARE THESE FILES?
---------------------
This distribution consists of the following:
README - What you're reading now.
LICENSE - GNU Copyleft license.
src/ - Source code for barplot
barplot.c - barplot main program
barplot.h - barplot include file.
bphelp.c - barplot help file.
test.data - Test data
test.jpg - The results of running test.data :^)
Win32/
BARPLOT.EXE - Statically linked Win32 Binary
make_barplot.bat (simple make script for Win32 & VC 5.0)
Linux-ELF/
barplot - Statically linked ELF binary for Linux
make_barplot.sh (simple make script for linux)
Web/ - Webserver Stuff
notes - Some server notes.
image_out.php3 - PHP3 script to show .JPG image inline.
Tutorial/
tut_1.dat - Tutorial data
tut_1.jpg - Resultant .JPG file
----------------------------------------------------------------
Binary MD5SUM Information
Linux-ELF
md5sum barplot
82566b1ef37f7d7e11b730e2a1caffd9 barplot
Win32
md5sum barplot.exe
fec6758e5ea9cd90e4e0d1b76e9b2320 barplot.exe
----------------------------------------------------------------
Note:
Barplot links against several other packages, and requires these
libraries to compile:
ZLIB - Zlib compression library
LIBPNG - PNG Library
GD - Graphics Draw Library
(Note: GD requires the jpeg library to compile)
The following URLs may be helpful in finding these packages:
zlib - http://www.gnu.org/gnulist/production/zlib.html
libpng - http://www.libpng.org/pub/png/libpng.html
gd - http://www.boutell.com/gd/index.html
libjpeg - ftp://ftp.uu.net/graphics/jpeg/
HOW DO I USE IT?
----------------
We're going to explore the language of barplot, and see how we can
use it for ourselves. The following script (the typed passages
after the '>' character) is available as /tutorial/tut_1.dat
We want to create a file called my_1st.jpg from a file containing
these commands. Open your favorite editor, and create a file by
typing in the commands that follow the '>' character below. When
you're finished, you will have a file that is very close to the
tut_1.dat file, and which you can edit as we go along.
You can type these commands in directly, if you like, by running
barplot with the "input from stdin" filename.
barplot - my_1st.jpg
TO BEGIN:
1) Determine the size of the required output image.
barplot generates .JPG images, and *you* have complete control over
the size of the resultant image. Depending on the end usage, you
may want a small bar or a large bar. You decide.
We'll choose to have a bar that is 200 x 30 (LxW) pixels.
2) Do you want each spread (or section of bar, if there are multiple
sections) to start with a black indicator bar?
barplots "bar" can consist of one or more spreads, or sections,
and the start of each section can be indicated on the bar.
We'll choose not to do this. No=0, Yes=1. So "0"
3) Do you want to have regular "tic" marks along the length of the
bar? If so, how many?
barplot indicate relative positioning by subdividing the bar into
sections. For example, you may wish to divide the output bar into
quarters, or tenths.
We'll choose to divide the bar into fourths. So "4".
3b) (Optional) Generate a second image with a percent complete value?
barplot can optionally generate two seperate .JPG files, a .JPG
image of the bar, and a .JPG image of the percent complete value.
This can be helpful in static reports, when you are generating a
large number of bars at a time, and are pasting them into some
sort of report. You can not use this option and get meaningful
output from stdout.
Great, you have defined the output bar parameters! The first line of
input to barplot will look like this:
BAR <length> <width> <start marks> <divisions> [percent complete image]
>BAR 200 30 0 4
4) Define the scale of the bar.
barplot needs to know the beginning and end points of your overall
bar. If this bar represents mileage, for example, you have to
define the start and end points of the bar.
Our bar represents miles from 0 to 7.5
>BAR_MIN_MAX 0 7.5
5) Define the background color of the bar.
barplot needs to know the background color of the bar. The
background color can be any of the seven predefined colors, or
either of the two user defined colors. Do step 6 first if you
wish to use a defined color as the background.
Our bar has a white background
>BGCOLOR WHITE
6) Define any unique colors you'd like to use. This is optional.
barplot gives you the ability to define two colors, apart from the
predefined colors WHITE,BLUE,RED,BLACK,YELLOW,GREY and GREEN. You
define these colors by telling barplot what color you want to
define (COLOR1 or COLOR2) and the Red,Green,Blue values of that
color. For example, let's say I want a pink background COLOR1,
I would issue this command to barplot: COLOR1 255 102 204
NOTE: If you are going to use a unique color for your
background, you MUST define that unique color as the first
defined color.
Our bar does not require any unique colors.
7) Define your first spread.
Every bar has at least one spread. A spread can take the length of the
entire bar, or be just a small part of the bar. It is often useful to
know the start and end points of the spread with respect to the bar
itself. The spread can, optionally, have a default color for items in
that spread.
Our first spread is from 0 to 3.825 miles, and we want the default
color of our items to be blue.
>SPREAD 0.0000 3.825 BLUE
8) Define data points for your spread.
We have four data points to indicate on the spread, three are normal and
one is, say, in trouble :^)
>0.0379 0.9193
>0.9193 2.2034
>2.2034 4.4750 RED
>4.4750 5.1250
Note that the data does not need to fill the entire spread, and can
represent whatever we want in the bar.
9) End your spread
barplot need to know when the data for your spread is finished. The
command for this is simple: END
>END
Let's define another spread.
>SPREAD 3.825 7.5 GREEN
and some data for that spread
>0.1275 0.3750
>2.2500 2.7500 YELLOW
>2.7500 3.3750 RED
Note how the data points relate to the SPREAD and not to the BAR itself.
We don't need to have spread start/stop information, though. We could
also have written the above four lines as:
>SPREAD
>3.9525 4.2000 GREEN
>6.0750 6.5750 YELLOW
>6.5750 7.2000 RED
and created a bar that looked identical. Spreads are very useful when
we get data from the field about a certain area, and the measurements
are relative to that area only. We don't have to do the math, barplot
does it for us!
End the spread
>END
Finally, we want to end our bar and write the file.
>BAR_END
Save the file and run it through barplot as follows:
barplot <filename> my_1st.jpg
That does it!
A quick look at the resulting .JPG file should show it to be exactly like
\tutorial\tut_1.jpg
What about percent complete information? Glad you asked :^)
Because barplot is very flexible in presenting information to the user,
the definition of "percent complete" can vary from bar to bar. Is the
user interested in the amount of BLUE represented in the bar? Perhaps
a more telling statistic is how much is NOT reported, or what percent is
RED (assuming that RED means something on this bar)
A quick statistic, how much has been reported, is given by:
barplot <filename> NULL NULL
This calls barplot with your data file, and tells it to *not* generate
any .JPG files, but to calculate the representative percentage of reported
areas. You should get the following answer on your command line: 68.83
To get the representative percentage of the BLUE items, do this:
barplot <filename> NULL NULL blue
and you get: 28.87
barplot <filename> NULL NULL white
gives you the UNREPORTED percentage, which is 31.17
You can get the percentage of any combination of colors by including them
on the command line:
barplot <filename> NULL NULL blue red green yellow
gives you 68.83, which is identical to leaving out the colors altogether.
barplot <filename> NULL NULL blue green yellow
gives you 38.84, the amount of NON-RED, reported items.
LICENSING
---------
barplot is licensed under the GNU general license, and is free software.
barplot is linked to libraries that are also released free to the public under
the GNU license, or similiar licenses.
The software was developed at Gulf Interstate Engineering by Jim Delahanty.
If you find it useful, you can drop me a note. I welcome comments, patches,
and suggestions for improvements.
If you're interested in writing man pages, configure scripts or makefiles,
by all means, be my guest!
The following header has been prepended to all applicable files in the
distribution:
/****************************************************************************\
barplot - scaled linear progress bar .JPG generator.
Copyright (c) 2000 James Delahanty - Gulf Interstate Engineering
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
Send comments, suggestions for improvements, any code you'd like to share
or just random thoughts to jimd@gie.com
or, if you'd like, you can mail them to:
Jim Delahanty,
c/o Gulf Interstate Engineering
Suite 600
1700 West Loop South
Houston, TX 77027
\****************************************************************************/
