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