packages icon
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

\****************************************************************************/