NAME
Image::Timeline - Create GIF or PNG timelines
SYNOPSIS
use Image::Timeline;
my $t = new Image::Timeline(width => 400);
$t->add('J.S. Bach', 1685, 1750);
$t->add('Beethoven', 1770, 1827);
$t->add('Brahms', 1833, 1897);
$t->add('Ravel', 1875, 1937);
...
# For older versions of GD:
$t->write_gif('composers.gif');
# For newer versions of GD:
$t->write_png('composers.png');
# Get the GD object
my $img = $t->draw;
DESCRIPTION
This module creates bar-format timelines using the GD.pm module.
Depending on the version of GD you have, you can produce either GIF or
PNG files.
See the file `t/truth.gif' for example output.
METHODS
new()
Creates a new timeline object. Accepts several named parameters that
affect how the timeline is created:
* width
How many pixels wide the image should be. Default is 900 pixels, for
no good reason.
* font
Which GD font should be used to label each entry in the timeline.
Default is `gdTinyFont'.
* bar_stepsize
The "tick interval" on the timeline's legend at the top. Default is
50 (i.e. 50 years).
* vspacing
How many pixels of vertical space should be left between entries.
Default is 2.
* hmargin
How many pixels should be left at the far right and far left of the
image. Default is 3.
* bg_color
* bar_color
* endcap_color
* legend_color
* text_color
These parameters affect the colors of the image. Each associated
value should be a 3-element array reference, specifying RGB values
from 0 to 255. For instance, the default value of `bar_color' is
pure red, specified as `[255,0,0]'. The defaults are reasonable, but
not necessarily attractive.
add(label, start, end)
Adds a new entry to the timeline. Supply a label that you want to
include in the image, the starting date, and the ending date.
draw()
Creates the `GD' object and returns it. This method is where all the
real work is done - the code must figure out things like how to squeeze
the entries most compactly but avoid collisions between bars, when to
draw labels above their bars and when below (again, to avoid collisions
between labels), the image's height (a function of how many concurrent
entries it contains), and so on.
write_png(filename)
write_gif(filename)
A convenience method which writes the timeline to a file. Because of
some Unisys/Compuserve/GD patent issues that I don't want to get
involved in, writing PNG output requires a version of GD newer than
1.19, while writing GIF output requires GD version 1.19 or older.
LIMITATIONS
Currently all dates/times are specified as integers, which are meant to
represent years. Finer granularity (time of day) isn't supported yet,
but it probably could be if it's desired (or someone gives me a patch).
Doesn't yet fully test the PNG capabilities during 'make test'. This is
just because I haven't yet found time to build all the necessary PNG
libraries on my system, so I haven't gotten the benchmark image built.
Please let me know whether this works correctly, and maybe even send me
the 't/testdata.png' file created so I can include it here.
AUTHOR
Ken Williams,
[email protected]
COPYRIGHT
Copyright 2001 Ken Williams. All rights reserved.
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
SEE ALSO
perl(1), GD(3)
