|
DBD::Chart::Plot - Graph/chart Plotting engine for DBD::Chart |
new()setOptions()setPoints()plot()getMap()
DBD::Chart::Plot - Graph/chart Plotting engine for DBD::Chart
use DBD::Chart::Plot;
my $img = DBD::Chart::Plot->new();
my $anotherImg = DBD::Chart::Plot->new($image_width, $image_height);
$img->setPoints(\@xdataset, \@ydataset, 'blue line nopoints');
$img->setOptions (
horizMargin => 75,
vertMargin => 100,
title => 'My Graph Title',
xAxisLabel => 'my X label',
yAxisLabel => 'my Y label' );
print $img->plot;
DBD::Chart::Plot creates images of various types of graphs for 2 or 3 dimensional data. Unlike GD::Graph, the input data sets do not need to be uniformly distributed in the domain (X-axis), and may be either numeric, temporal, or symbolic.
DBD::Chart::Plot supports the following:
new()
use DBD::Chart::Plot;
my $img = DBD::Chart::Plot->new;
my $img = DBD::Chart::Plot->new ( $image_width, $image_height );
my $img = DBD::Chart::Plot->new ( $image_width, $image_height, \%colormap );
my $anotherImg = new DBD::Chart::Plot;
Creates an empty image. If image size is not specified, the default is 400 x 300 pixels.
setOptions()
$img->setOptions (_title => 'My Graph Title',
xAxisLabel => 'my X label',
yAxisLabel => 'my Y label',
xLog => 0,
yLog => 0,
horizMargin => $numHorPixels,
vertMargin => $numvertPixels,
horizGrid => 1,
vertGrid => 1,
showValues => 1,
legend => \@plotnames,
genMap => 'a_valid_HTML_anchor_name',
mapURL => 'http://some.website.com/cgi-bin/cgi.pl',
icon => [ 'redstar.png', 'bluestar.png' ]
symDomain => 0
);
As many (or few) of the options may be specified as desired.
If mapType is 'PERL', then Perl script compatible text is generated representing an array ref of hashrefs containing the following attributes:
plotnum => the plot number to which this hashref applies (to support multi-range graphs), starting at zero.
x => the domain value for the plot element
y => the range value for the plot element
z => the Z axis value for 3-axis bar charts, if any
shape => the shape of the hotspot area of the plot element, same as for HTML: 'RECT', 'CIRCLE', 'POLY'
coordinates => an arrayref of the (x,y) pixel coordinates of the hotspot area to be mapped; for CIRCLE shape, its (x-center, y-center, radius), for RECT, its (upper-left corner x, upper-left corner y, lower-right corner x, lower-right corner y), and for POLY its the set of vertices (x,y)'s.
If the mapType is 'HTML', then either the mapURL or mapScript (or both) can be specified. mapURL specifies a legal URL string, e.g., 'http://www.mysite.com/cgi-bin/plotproc.pl?plotnum=:PLOTNUM&X=:X&Y=:Y', which will be added to the AREA tags generated for each mapped plot element. mapScript specifies any legal HTML scripting tag, e.g., 'ONCLICK=``alert('Got X=:X, Y=:Y')''' to be added to each generated AREA tag.
For both mapURL and mapScript, special variables :PLOTNUM, :X, :Y, :Z can be specified which are replaced by the following values when the imagemap is generated.
Refer to the IMAGEMAP description at www.presicient.com/dbdchart#imagemap for details.
setPoints() function (defined below). The array must
match 1-to-1 with the number of plots in the image; icons
and predefined point shapes can be mixed in the same image
by setting the icon arrayref entry to undef for plots using
predefined shapes in the properties string.
By default, the graph will be centered within the image, with 50 pixel margin around the graph border. You can obtain more space for titles or labels by increasing the image size or increasing the margin values.
setPoints()
$img->setPoints(\@xdata, \@ydata);
$img->setPoints(\@xdata, \@ydata, 'blue line');
$img->setPoints(\@xdata, \@ymindata, \@ymaxdata, 'blue points');
$img->setPoints(\@xdata, \@ydata, \@zdata, 'blue bar zaxis');
Copies the input array values for later plotting.
May be called repeatedly to establish multiple plots in a single graph.
Returns a positive integer on success and undef on failure.
The global graph properties should be set (via setOptions())
prior to setting the data points.
The error() method can be used to retrieve an error message.
X-axis values may be non-numeric, in which case the set of domain values
is uniformly distributed along the X-axis. Numeric X-axis data will be
properly scaled, including logarithmic scaling is requested.
If two sets of range data (ymindata and ymaxdata in the example above) are supplied, and the properties string does not specify a 3-axis barchart, a candlestick graph is rendered, in which case the domain data is assumed non-numeric and is uniformly distributed, the first range data array is used as the bottom value, and the second range data array is used as the top value of each candlestick. Pointshapes may be specified, in which case the top and bottom of each stick will be capped with the specified pointshape. The range and/or domain axis may be logarithmically scaled. If value display is requested, the range value of both the top and bottom of each stick will be printed above and below the stick, respectively.
Plot properties: Properties of each dataset plot can be set with an optional string as the third argument. Properties are separated by spaces. The following properties may be set on a per-plot basis (defaults in capitals):
COLOR CHARTSTYLE USE POINTS? POINTSHAPE
----- --------- ----------- ----------
BLACK LINE POINTS FILLCIRCLE
white noline nopoints opencircle
lgray fill fillsquare
gray bar opensquare
dgray pie filldiamond
lblue box opendiamond
blue zaxis horizcross
dblue histo diagcross
gold icon
lyellow dot
yellow
dyellow
lgreen
green
dgreen
lred
red
dred
lpurple
purple
dpurple
lorange
orange
pink
dpink
marine
cyan
lbrown
dbrown
E.g., if you want a red scatter plot (red dots but no lines) with filled diamonds, you could specify
$p->setPoints (\@xdata, \@ydata, 'Points Noline Red filldiamond');
Specifying icon for the pointshape requires setting the icon object attribute to a list of compatible image filenames (as an arrayref, see below). In that case, the icon images are displayed centered on the associated plotpoints. For 2-D barcharts, a stack of the icon is used to display the bars, including a proportionally clipped icon image to cap the bar if needed.
plot()
$img->plot();
Draws the image and returns it as a string. To save the image to a file:
open (WR,'>plot.png') or die ("Failed to write file: $!");
binmode WR; # for DOSish platforms
print WR $img->plot();
close WR;
To return the graph to a browser via HTTP:
print "Content-type: image/png\n\n";
print $img->plot();
The range of values on each axis is automatically computed to optimize the data placement in the largest possible area of the image. As a result, the origin (0, 0) axes may be omitted if none of the datasets cross them at any point. Instead, the axes will be drawn on the left and bottom borders using the value ranges that appropriately fit the dataset(s).
getMap()
$img->getMap();
Returns the imagemap for the chart. If no mapType was set, or if mapType was set to HTML. the returned value is a valid <MAP...><AREA...></MAP> HTML string. If mapType was set to 'Perl', a Perl-compatible arrayref declaration string is returned.
The resulting imagemap will be applied as follows:
X=<wedge-label>&Y=<wedge-value>&Z=<wedge-percent>
Copyright (c) 2001 by Presicient Corporation. (darnold@presicient.com)
You may distribute this module under the terms of the Artistic License, as specified in the Perl README file.
GD, DBD::Chart. (All available on CPAN).
|
DBD::Chart::Plot - Graph/chart Plotting engine for DBD::Chart |