patches from Patrick Michaud
[imager-graph.git] / README
CommitLineData
a69600d8 1Copyright 2000-2002,2007 Anthony Cook. All rights reserved.
35574351
TC
2This program is free software, you can redistribute it and/or
3modify it under the same terms as Perl itself.
4
5
6What is it?
7===========
8
9Imager::Graph is intended to produce good looking graphs with a
10minimum effort on the part of the user. Hopefully I've managed that.
11
12Currently only the pie graph class, Imager::Graph::Pie, is provided.
13
14
35574351
TC
15Fonts
16=====
17
18For best results you will need one or more attractive fonts, and one
19of the outline font libraries that Imager supports. The ImUgly font
20is supplied with Imager::Graph, but it is fairly ugly, so probably
21isn't useful if you want nice output.
22
23
24Installation
25============
26
27Imager::Graph follows the normal perl module installation process:
28
29 perl Makefile.PL
30 make
31 make test
32 make install
33
34Please Note: don't be too suprised if you get test failures,
35unfortunately minor changes in the image can result in large changes
36in the measure I use to check the results. If you get test failures
37please check the results in testout/
38
39The tests require PNG file format and TrueType font format support.
40
41Creating Graphs
42===============
43
44The aim is to make things as simple as possible, if you have some data
45you can create a pie chart with:
46
47 use Imager::Graph::Pie;
48
49 my $font = Imager::Font->new(file=>$fontfile)
50 or die "Cannot create font: ",Imager->errstr;
51 my $pie_graph = Imager::Graph::Pie->new();
52 my $img = $pie_graph->draw(data=>\@data);
53
54If you want to add a legend, you need to provide some descriptive text
55as well:
56
57 my $img = $pie_graph->draw(data=>\@data, labels=>\@labels, font=>$font,
58 features=>'legend');
59
60You might want to add a title instead:
61
62 my $img = $pie_graph->draw(data=>\@data, font=>$font, title=>'MyGraph');
63
64or instead of a legend, use callouts to annotate each segment:
65
66 my $img = $pie_graph->draw(data=>\@data, labels=>\@labels,
67 features=>'allcallouts', font=>$font);
68
69(The following graphs use features introduce after Imager 0.38.)
70
71If you want draw a monochrome pie graph, using hatched fills, specify
72the 'mono' style:
73
74 my $img = $pie_graph->draw(data=>\@data, style=>'mono');
75
76The 'mono' style produces a 1 channel image by default, so if you want
77to add some color you need to reset the number of channels, for
78example, you could change the drawing color to red:
79
80 my $img = $pie_graph->draw(data=>\@data, style=>'mono',
81 fg=>'FF0000', channels=>3);
82
83
84If you're feeling particularly adventurous, you could create a graph
85with a transparent background, suitable for compositing onto another
86image:
87
88 my $img = $pie_graph->draw(data=>\@data, style=>'mono',
89 bg=>'00000000', channels=>4);
90
91If you only want the background of the graph to be transparent, while leaving other parts of the chart opaque, use the back option:
92
93 my $img = $pie_graph->draw(data=>\@data, style=>'mono',
94 back=>'00000000', channels=>4);
95
96or you could make the background an image based fill:
97
98 my $img = $pie_graph->draw(data=>\@data, style=>'mono', channels=>4,
99 back=>{ image=>$otherimage } );
100
101If you want a "prettier" image, you could use one of the fountain fill
102based styles:
103
104 my $img = $pie_graph->draw(data=>\@data, style=>'fount_lin');
105
106The image you receive from Imager::Graph is a normal Imager image,
107typically an 8-bit/sample direct color image, though options to extend
108that may be introduced in the future.
109
110
111Portability
112===========
113
114Imager::Graph should work on any system that Imager works on.
115
116
117More Information
118================
119
120If you have queries about Imager::Graph, please email me at
121tony@develop-help.com.
122
123A PPM compatible version of this module should be available from
124http://ppd.develop-help.com/.
125
126Thanks go to Addi for Imager.
127
128