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