#------------------------------------------------------------
#The cuttlefish Visualization Tool.
#Copyright (C) 2006 The Regents of the University of California.
#
#This program is free software; you can redistribute it and/or modify it
#under the terms of the GNU General Public License version 2 as published 
#by the Free Software Foundation. 
#
#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
#
#written by Bradley Huffaker <bradley@caida.org>
#
#documention by Joshua Polterock <josh@caida.org>
#	       Bradley Huffaker <bradley@caida.org>
#	       Marina Fomenkova <marina@caida.org>
#
#------------------------------------------------------------


######################################################################
    cuttlefish

	Cuttlefish produces animated GIFs that reveal the interplay
	between the diurnal and geographical patterns of displayed
	data. By showing how the Sun's shadow covers the world map,
	cuttlefish yields a direct feeling for the time of day at
	a given geographic region, while moving graphs illustrate
	the relationship between local time and the visualized
	events.

	Cuttlefish lives on the web at
	/tools/visualization/cuttlefish/ .

    Cuttlefish was developed with support and funding from:

    CAIDA - /    
    SDSC  - http://www.sdsc.edu/
    WIDE  - http://www.wide.ad.jp/

######################################################################

executables:
    bin/cuttlefish.pl
	This program reads a configuration file and then generates an
	animation.
	output file.

configuration file sample:
    configs/japan-traces.config
	This is a sample configuration file and is the output of 
	bin/parse-japan-trace-data.pl

images:
    images/world-water.jpg
	This is the water image used to create the background of world map. 

    images/japan-water.jpg
	This is the water image used to create the background of japan map.

    images/japan-water-okinawa.jpg
	This is the water image used to create the Okinawa world map.

libraries:
    lib/Canvas.pm
	This is a general purpose wrapper for GD::Image.   It doesn't 
	reproduce all the functions of Image, since you can get them
	directly, but adds a few helper functions.
    lib/Colorkey.pm
	This is the code that draws the Color Key.
    lib/Control.pm
	This is the code that parses the configuration file and 
	stores the resulting values.
    lib/Dates.pl
	This is a collection of functions to handle Dates and Unix
	timestamps.
    lib/Histogram.pm
	This is the code that draws the Histogram.
    lib/Map.pm
	This code handles the maps which are drawn on the final image.
    lib/Util.pl
	This code has a few useful functions.

===============================================================
Required external libraries and executables
===============================================================

    You will need to install PERL's interface to GD, ImageMagick and
    gifsicle.
	http://search.cpan.org/dist/GD/
	    GD - is used to create the images.
	http://www.ImageMagick.org/script/index.php
	    convert - is used to convert the png files to gif images,
	    since GD's gif library is not dependable.
	http://www.lcdf.org/gifsicle/
	    gifsicle - combines the individual GIFs to form an animation.
	    Although the cuttlefish will use convert if gifsicle is not
	    found gifsicle has much nicer compression code.  Using gifsicle
	    instead of convert can decrease file sizes by half.