lib/Imager/Tutorial.pod

   1 =head1 NAME
   2
   3 Imager::Tutorial - an introduction to Imager.
   4
   5 =head1 DESCRIPTION
   6
   7 =head2 Before you start
   8
   9 If you have the necessary knowledge, install the image format
  10 libraries you want Imager image file support for, and Imager itself,
  11 otherwise arrange to have it done.
  12
  13 You will also want some sort of image viewer tool, whether an image
  14 editor like Photoshop or the GIMP, or a web browser.
  15
  16 =head2 Hello Boxes! - A Simple Start
  17
  18 As with any perl program it's useful to start with a #! line, and to
  19 enable strict mode:
  20
  21   #!/usr/bin/perl -w
  22   # you might to 'use warnings;' instead of the -w above
  23   use strict;
  24
  25 These lines will be omitted in further examples.
  26
  27 As with any module, you need to load it:
  28
  29   use Imager;
  30
  31 Now create a image to draw on:
  32
  33   my $image = Imager->new(xsize => 100, ysize => 100);
  34
  35 and draw a couple of filled rectangles on it:
  36
  37   $image->box(xmin => 0, ymin => 0, xmax => 99, ymax => 99,
  38               filled => 1, color => 'blue');
  39   $image->box(xmin => 20, ymin => 20, xmax => 79, ymax => 79,
  40               filled => 1, color => 'green');
  41
  42 Since the first box fills the whole image, it can be simplified to:
  43
  44   $image->box(filled => 1, color => 'blue');
  45
  46 and save it to a file:
  47
  48   $image->write(file=>'tutorial1.ppm')
  49       or die 'Cannot save tutorial1.ppm: ', $image->errstr;
  50
  51 So our completed program is:
  52
  53   use Imager;
  54
  55   my $image = Imager->new(xsize => 100, ysize => 100);
  56
  57   $image->box(filled => 1, color => 'blue');
  58   $image->box(xmin => 20, ymin => 20, xmax => 79, ymax => 79,
  59               filled => 1, color => 'green');
  60
  61   $image->write(file=>'tutorial1.ppm')
  62       or die 'Cannot save tutorial1.ppm: ', $image->errstr;
  63
  64 =head2 Adding some text
  65
  66 The first thing you need to draw text is a font object:
  67
  68   # use a different file, depending on the font support you have in
  69   # your installed Imager.
  70   my $font_filename = 'fontfiles/ImUgly.ttf';
  71   my $font = Imager::Font->new(file=>$font_filename)
  72     or die "Cannot load $font_filename: ", Imager->errstr;
  73
  74 If you're on Windows, you can supply a face name instead:
  75
  76   my $font = Imager::Font->new(face=>'Arial Bold')
  77     or die "Cannot load 'Arial Bold: ", Imager->errstr;
  78
  79 and draw the text:
  80
  81   my $text = "Hello Boxes!";
  82   my $text_size = 12;
  83
  84   $font->align(string => $text,
  85                size => $text_size,
  86                color => 'red',
  87                x => $image->getwidth/2,
  88                y => $image->getheight/2,
  89                halign => 'center',
  90                valign => 'center',
  91                image => $image);
  92
  93 So inserting this into our existing code we have:
  94
  95   use Imager;
  96
  97   my $image = Imager->new(xsize => 100, ysize => 100);
  98
  99   $image->box(xmin => 0, ymin => 0, xmax => 99, ymax => 99,
 100               filled => 1, color => 'blue');
 101   $image->box(xmin => 20, ymin => 20, xmax => 79, ymax => 79,
 102               filled => 1, color => 'green');
 103
 104   # use a different file, depending on the font support you have in
 105   # your installed Imager.
 106   my $font_filename = 'fontfiles/ImUgly.ttf';
 107   my $font = Imager::Font->new(file=>$font_filename)
 108     or die "Cannot load $font_filename: ", Imager->errstr;
 109
 110   my $text = "Hello Boxes!";
 111   my $text_size = 12;
 112
 113   $font->align(string => $text,
 114                size => $text_size,
 115                color => 'red',
 116                x => $image->getwidth/2,
 117                y => $image->getheight/2,
 118                halign => 'center',
 119                valign => 'center',
 120                image => $image);
 121
 122   $image->write(file=>'tutorial2.ppm')
 123       or die 'Cannot save tutorial2.ppm: ', $image->errstr;
 124
 125 =head2 Using an existing image as a base
 126
 127 To load an image from a file, first create an empty image object:
 128
 129   my $read_image = Imager->new;
 130
 131 then call the read method:
 132
 133   my $image_source = shift; # from the command-line
 134   $read_image->read(file=>$image_source)
 135     or die "Cannot load $image_source: ", $image->errstr;
 136
 137 To keep to our working size, we'll scale the image:
 138
 139   # the scale() method always does a proportional scale, we don't want
 140   # that here
 141   my $scaled_image = $read_image->scaleX(pixels=>100)->scaleY(pixels=>100);
 142
 143 draw our inner box on that, and save the result:
 144
 145   $scaled_image->box(xmin => 20, ymin => 20, xmax => 79, ymax => 79,
 146               filled => 1, color => 'green');
 147
 148   $scaled_image->write(file=>'tutorial3.ppm')
 149       or die 'Cannot save tutorial3.ppm: ', $image->errstr;
 150
 151 so the complete program is:
 152
 153   use Imager;
 154
 155   my $read_image = Imager->new;
 156
 157   my $image_source = shift; # from the command-line
 158   $read_image->read(file=>$image_source)
 159     or die "Cannot load $image_source: ", $image->errstr;
 160
 161   # the scale() method always does a proportional scale, we don't want
 162   # that here
 163   my $scaled_image = $read_image->scaleX(pixels=>100)->scaleY(pixels=>100);
 164
 165   $scaled_image->box(xmin => 20, ymin => 20, xmax => 79, ymax => 79,
 166               filled => 1, color => 'green');
 167
 168   $scaled_image->write(file=>'tutorial3.ppm')
 169       or die 'Cannot save tutorial3.ppm: ', $image->errstr;
 170
 171
 172 =head1 AUTHOR
 173
 174 Tony Cook <tony@imager.perl.org>
 175
 176 =head1 REVISION
 177
 178 $Revision$
 179
 180 =cut