.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Imager::Tutorial 3pm"
.TH Imager::Tutorial 3pm 2024-04-13 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Imager::Tutorial \- an introduction to Imager.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
.SS "Before you start"
.IX Subsection "Before you start"
If you have the necessary knowledge, install the image format
libraries you want Imager image file support for, and Imager itself,
otherwise arrange to have it done.
.PP
You will also want some sort of image viewer tool, whether an image
editor like Photoshop or the GIMP, or a web browser.
.SS "Hello Boxes! \- A Simple Start"
.IX Subsection "Hello Boxes! - A Simple Start"
As with any perl program it's useful to start with a #! line, and to
enable strict mode:
.PP
.Vb 3
\&  #!/usr/bin/perl \-w
\&  # you might to \*(Aquse warnings;\*(Aq instead of the \-w above
\&  use strict;
.Ve
.PP
These lines will be omitted in further examples.
.PP
As with any module, you need to load it:
.PP
.Vb 1
\&  use Imager;
.Ve
.PP
Now create a image to draw on:
.PP
.Vb 1
\&  my $image = Imager\->new(xsize => 100, ysize => 100);
.Ve
.PP
and draw a couple of filled rectangles on it:
.PP
.Vb 4
\&  $image\->box(xmin => 0, ymin => 0, xmax => 99, ymax => 99,
\&              filled => 1, color => \*(Aqblue\*(Aq);
\&  $image\->box(xmin => 20, ymin => 20, xmax => 79, ymax => 79,
\&              filled => 1, color => \*(Aqgreen\*(Aq);
.Ve
.PP
Since the first box fills the whole image, it can be simplified to:
.PP
.Vb 1
\&  $image\->box(filled => 1, color => \*(Aqblue\*(Aq);
.Ve
.PP
and save it to a file:
.PP
.Vb 2
\&  $image\->write(file=>\*(Aqtutorial1.ppm\*(Aq)
\&      or die \*(AqCannot save tutorial1.ppm: \*(Aq, $image\->errstr;
.Ve
.PP
So our completed program is:
.PP
.Vb 1
\&  use Imager;
\&  
\&  my $image = Imager\->new(xsize => 100, ysize => 100);
\&  
\&  $image\->box(filled => 1, color => \*(Aqblue\*(Aq);
\&  $image\->box(xmin => 20, ymin => 20, xmax => 79, ymax => 79,
\&              filled => 1, color => \*(Aqgreen\*(Aq);
\&  
\&  $image\->write(file=>\*(Aqtutorial1.ppm\*(Aq)
\&      or die \*(AqCannot save tutorial1.ppm: \*(Aq, $image\->errstr;
.Ve
.SS "Adding some text"
.IX Subsection "Adding some text"
The first thing you need to draw text is a font object:
.PP
.Vb 5
\&  # use a different file, depending on the font support you have in
\&  # your installed Imager.
\&  my $font_filename = \*(Aqfontfiles/ImUgly.ttf\*(Aq;
\&  my $font = Imager::Font\->new(file=>$font_filename)
\&    or die "Cannot load $font_filename: ", Imager\->errstr;
.Ve
.PP
If you're on Windows, you can supply a face name instead:
.PP
.Vb 2
\&  my $font = Imager::Font\->new(face=>\*(AqArial Bold\*(Aq)
\&    or die "Cannot load \*(AqArial Bold: ", Imager\->errstr;
.Ve
.PP
and draw the text:
.PP
.Vb 2
\&  my $text = "Hello Boxes!";
\&  my $text_size = 12;
\&  
\&  $font\->align(string => $text,
\&               size => $text_size,
\&               color => \*(Aqred\*(Aq,
\&               x => $image\->getwidth/2,
\&               y => $image\->getheight/2,
\&               halign => \*(Aqcenter\*(Aq,
\&               valign => \*(Aqcenter\*(Aq,
\&               image => $image);
.Ve
.PP
So inserting this into our existing code we have:
.PP
.Vb 1
\&  use Imager;
\&  
\&  my $image = Imager\->new(xsize => 100, ysize => 100);
\&  
\&  $image\->box(xmin => 0, ymin => 0, xmax => 99, ymax => 99,
\&              filled => 1, color => \*(Aqblue\*(Aq);
\&  $image\->box(xmin => 20, ymin => 20, xmax => 79, ymax => 79,
\&              filled => 1, color => \*(Aqgreen\*(Aq);
\&  
\&  # use a different file, depending on the font support you have in
\&  # your installed Imager.
\&  my $font_filename = \*(Aqfontfiles/ImUgly.ttf\*(Aq;
\&  my $font = Imager::Font\->new(file=>$font_filename)
\&    or die "Cannot load $font_filename: ", Imager\->errstr;
\&  
\&  my $text = "Hello Boxes!";
\&  my $text_size = 12;
\&  
\&  $font\->align(string => $text,
\&               size => $text_size,
\&               color => \*(Aqred\*(Aq,
\&               x => $image\->getwidth/2,
\&               y => $image\->getheight/2,
\&               halign => \*(Aqcenter\*(Aq,
\&               valign => \*(Aqcenter\*(Aq,
\&               image => $image);
\&  
\&  $image\->write(file=>\*(Aqtutorial2.ppm\*(Aq)
\&      or die \*(AqCannot save tutorial2.ppm: \*(Aq, $image\->errstr;
.Ve
.SS "Using an existing image as a base"
.IX Subsection "Using an existing image as a base"
To load an image from a file, first create an empty image object:
.PP
.Vb 1
\&  my $read_image = Imager\->new;
.Ve
.PP
then call the read method:
.PP
.Vb 3
\&  my $image_source = shift; # from the command\-line
\&  $read_image\->read(file=>$image_source)
\&    or die "Cannot load $image_source: ", $image\->errstr;
.Ve
.PP
To keep to our working size, we'll scale the image:
.PP
.Vb 3
\&  # the scale() method always does a proportional scale, we don\*(Aqt want
\&  # that here
\&  my $scaled_image = $read_image\->scaleX(pixels=>100)\->scaleY(pixels=>100);
.Ve
.PP
draw our inner box on that, and save the result:
.PP
.Vb 2
\&  $scaled_image\->box(xmin => 20, ymin => 20, xmax => 79, ymax => 79,
\&              filled => 1, color => \*(Aqgreen\*(Aq);
\&
\&  $scaled_image\->write(file=>\*(Aqtutorial3.ppm\*(Aq)
\&      or die \*(AqCannot save tutorial3.ppm: \*(Aq, $image\->errstr;
.Ve
.PP
so the complete program is:
.PP
.Vb 1
\&  use Imager;
\&
\&  my $read_image = Imager\->new;
\&
\&  my $image_source = shift; # from the command\-line
\&  $read_image\->read(file=>$image_source)
\&    or die "Cannot load $image_source: ", $image\->errstr;
\&
\&  # the scale() method always does a proportional scale, we don\*(Aqt want
\&  # that here
\&  my $scaled_image = $read_image\->scaleX(pixels=>100)\->scaleY(pixels=>100);
\&
\&  $scaled_image\->box(xmin => 20, ymin => 20, xmax => 79, ymax => 79,
\&              filled => 1, color => \*(Aqgreen\*(Aq);
\&
\&  $scaled_image\->write(file=>\*(Aqtutorial3.ppm\*(Aq)
\&      or die \*(AqCannot save tutorial3.ppm: \*(Aq, $image\->errstr;
.Ve
.SH AUTHOR
.IX Header "AUTHOR"
Tony Cook <tonyc@cpan.org>
.SH REVISION
.IX Header "REVISION"
\&\f(CW$Revision\fR$