README

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