README

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