• "x1", "y1" - starting point of the line. Required.
• "x2", "y2" - end point of the line. Required.
• "color" - the color of the line. See "Color Parameters". Default: black.
• "endp" - if zero the end point of the line is not drawn. Default: 1 - the end point is drawn. This is useful to set to 0 when drawing a series of connected lines.
• "aa" - if true the line is drawn anti-aliased. Default: 0.

• points - a reference to an array of references to arrays containing the co-ordinates of the points in the line, for example:

    my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] );
    $img->polyline(points => \@points);
      

• x, y - each is an array of x or y ordinates. This is an alternative to supplying the "points" parameter.

    # same as the above points example
    my @x = ( 0, 100, 100, 0 );
    my @y = ( 0, 0, 100, 100 );
    $img->polyline(x => \@x, y => \@y);
      

• "color" - the color of the line. See "Color Parameters". Default: black.
• "aa" - if true the line is drawn anti-aliased. Default: 0. Can also be supplied as "antialias" for backward compatibility.

• "xmin" - left side of the box. Default: 0 (left edge of the image)
• "ymin" - top side of the box. Default: 0 (top edge of the image)
• "xmax" - right side of the box. Default: "$img->getwidth-1". (right edge of the image)
• "ymax" - bottom side of the box. Default: "$img->getheight-1". (bottom edge of the image)

  Note: "xmax" and "ymax" are inclusive - the number of pixels drawn for a filled box is "(xmax-xmin+1) * (ymax-ymin+1)".

• "box" - a reference to an array of (left, top, right, bottom) co-ordinates. This is an alternative to supplying "xmin", "ymin", "xmax", "ymax" and overrides their values.
• "color" - the color of the line. See "Color Parameters". Default: white. This is ignored if the filled parameter
• "filled" - if non-zero the box is filled with color instead of outlined. Default: an outline is drawn.
• "fill" - the fill for the box. If this is supplied then the box will be filled. See "Fill Parameters".

• "x", "y" - center of the filled arc. Default: center of the image.
• "r" - radius of the arc. Default: 1/3 of min(image height, image width).
• "d1" - starting angle of the arc, in degrees. Default: 0
• "d2" - ending angle of the arc, in degrees. Default: 361.
• "color" - the color of the filled arc. See "Color Parameters". Default: white. Overridden by "fill".
• "fill" - the fill for the filled arc. See "Fill Parameters"
• "aa" - if true the filled arc is drawn anti-aliased. Default: false.

  Anti-aliased arc() is experimental for now, I'm not entirely happy with the results in some cases.

• "filled" - set to 0 to draw only an outline.

  # arc going through angle zero:
  $img->arc(d1=>320, d2=>40, x=>100, y=>100, r=>50, color=>'blue');

  # complex fill arc
  $img->arc(d1=>135, d2=>45, x=>100, y=>150, r=>50, 
            fill=>{ solid=>'red', combine=>'diff' });

  # draw an anti-aliased circle outline
  $img->arc(x => 100, y => 150, r => 150, filled => 0, 
            color => '#F00', aa => 1);

  # draw an anti-aliased arc
  $img->arc(x => 100, y => 150, r => 90, filled => 0,
            color => '#0f0', aa => 1, d1 => 90, d2 => 180);

• "x", "y" - center of the filled circle. Default: center of the image.
• "r" - radius of the circle. Default: 1/3 of min(image height, image width).
• "color" - the color of the filled circle. See "Color Parameters". Default: white. Overridden by "fill".
• "fill" - the fill for the filled circle. See "Fill Parameters"
• "aa" - if true the filled circle is drawn anti-aliased. Default: false.
• "filled" - set to 0 to just draw an outline.

• "points" - a reference to an array of references to arrays containing the co-ordinates of the points in the line, for example:

    my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] );
    $img->polygon(points => \@points);
      

• "x", "y" - each is an array of x or y ordinates. This is an alternative to supplying the "points" parameter.

    # same as the above points example
    my @x = ( 0, 100, 100, 0 );
    my @y = ( 0, 0, 100, 100 );
    $img->polygon(x => \@x, y => \@y);
      

• "color" - the color of the filled polygon. See "Color Parameters". Default: black. Overridden by "fill".
• "fill" - the fill for the filled circle. See "Fill Parameters"
• "mode" - fill mode for the polygon. See "Polygon Fill Modes"

Note: the points specified are as offsets from the top-left of the image, not as pixel locations. This means that:

  $img->polygon(points => [ [ 0, 0 ], [ 1, 0 ], [ 1, 1 ], [ 0, 1 ] ]);

fills only a single pixel at "(0, 0)", not four.

• "points" - is an array reference containing polygon definitions, each polygon definition is a reference to an array containing two arrays, one each for the "x" and "y" co-ordinates.
• "filled" - if true, fill the polygons with the color defined by "color".
• "color" - the color to draw the polygons with if "fill" is not supplied.
• "fill" - fill the polygons with this fill if supplied.
• "mode" - fill mode for the polygon. See "Polygon Fill Modes"

Note: the points specified are as offsets from the top-left of the image, not as pixel locations. This means that:

  $img->polypolygon(points => [ [ [ 0, 1, 1, 0 ], [ 0, 0, 1, 1 ] ] ],
                    filled => 1);

fills only a single pixel at "(0, 0)", not four.

• "x", "y" - the start point of the fill.
• "color" - the color of the filled area. See "Color Parameters". Default: white. Overridden by "fill".
• "fill" - the fill for the filled area. See "Fill Parameters"
• "border" - the border color of the region to be filled. If this parameter is supplied flood_fill() will stop when it finds this color. If this is not supplied then a normal fill is done. "border" can be supplied as a "Color Parameters".

• x, y - either integers giving the co-ordinates of the pixel to set or array references containing a set of pixels to be set.
• color - the color of the pixels drawn. See "Color Parameters". Default: white.

Returns the number of pixels drawn, if no pixels were drawn, but none of the errors below occur, returns "0 but true".

For other errors, setpixel() returns an empty list and sets errstr().

Possible errors conditions include:

• the image supplied is empty
• a reference to an empty array was supplied for "x" or "y"
• "x" or "y" wasn't supplied
• "color" isn't a valid color, and can't be converted to a color.

• "x", "y" - either integers giving the co-ordinates of the pixel to set or array references containing a set of pixels to be set.
• "type" - the type of color object to return, either '8bit' for Imager::Color objects or 'float' for Imager::Color::Float objects. Default: '8bit'.

When called with an array reference for either or "x" or "y", getpixel() will return a list of colors in list context, and an arrayref in scalar context.

If a supplied co-ordinate is outside the image then "undef" is returned for the pixel.

Each color is returned as an Imager::Color object or as an Imager::Color::Float object if "type" is set to "float".

Possible errors conditions include:

• the image supplied is empty
• a reference to an empty array was supplied for "x" or "y"
• "x" or "y" wasn't supplied
• "type" isn't a valid value.

For any of these errors getpixel() returns an empty list.

• "x", "y" - the point to draw the text from. If "align" is 0 this is the top left of the string. If "align" is 1 (the default) then this is the left of the string on the baseline. Required.
• "string" - the text to draw. Required unless you supply the "text" parameter.
• "font" - an Imager::Font object representing the font to draw the text with. Required.
• "aa" - if non-zero the output will be anti-aliased. Default: the value set in Imager::Font->new() or 0 if not set.
• "align" - if non-zero the point supplied in (x,y) will be on the base-line, if zero then (x,y) will be at the top-left of the string.

  i.e. if drawing the string "yA" and align is 0 the point (x,y) will aligned with the top of the A. If align is 1 (the default) it will be aligned with the baseline of the font, typically bottom of the A, depending on the font used.

  Default: the value set in Imager::Font->new, or 1 if not set.

• "channel" - if present, the text will be written to the specified channel of the image and the color parameter will be ignore.
• "color" - the color to draw the text in. Default: the color supplied to Imager::Font->new, or red if none.
• "size" - the point size to draw the text at. Default: the size supplied to Imager::Font->new, or 15.
• "sizew" - the width scaling to draw the text at. Default: the value of "size".
• "utf8" - for drivers that support it, treat the string as UTF-8 encoded. For versions of perl that support Unicode (5.6 and later), this will be enabled automatically if the "string" parameter is already a UTF-8 string. See "UTF-8" in Imager::Font for more information.
• "vlayout" - for drivers that support it, draw the text vertically. Note: I haven't found a font that has the appropriate metrics yet.
• "text" - alias for the "string" parameter.

On error, string() returns false and you can use $img->errstr to get the reason for the error.

• "x", "y" - the point to draw the text from. If "align" is 0 this is the top left of the string. If "align" is 1 (the default) then this is the left of the string on the baseline. Required.
• "string" - the text to draw. Required unless you supply the "text" parameter.
• "font" - an Imager::Font object representing the font to draw the text with. Required.
• "aa" - if non-zero the output will be anti-aliased
• "valign" - vertical alignment of the text against (x,y)

•

"halign" - horizontal alignment of the text against (x,y)

• "channel" - if present, the text will be written to the specified channel of the image and the color parameter will be ignore.
• "color" - the color to draw the text in. Default: the color supplied to Imager::Font->new, or red if none.
• "size" - the point size to draw the text at. Default: the size supplied to Imager::Font->new, or 15.
• "sizew" - the width scaling to draw the text at. Default: the value of "size".
• "utf8" - for drivers that support it, treat the string as UTF-8 encoded. For versions of perl that support Unicode (5.6 and later), this will be enabled automatically if the "string" parameter is already a UTF-8 string. See "UTF-8" in Imager::Font for more information.
• "vlayout" - for drivers that support it, draw the text vertically. Note: I haven't found a font that has the appropriate metrics yet.
• "text" - alias for the "string" parameter.

On success returns a list of bounds of the drawn text, in the order left, top, right, bottom.

On error, align_string() returns an empty list and you can use "$img->errstr" to get the reason for the error.

• "y" - vertical position of the scan line. This parameter is required.
• "x" - position to start on the scan line. Default: 0
• "pixels" - either a reference to an array containing Imager::Color objects, an reference to an array containing Imager::Color::Float objects or a scalar containing packed color data.

  If "type" is "index" then this can either be a reference to an array of palette color indexes or a scalar containing packed indexes.

  See "Packed Color Data" for information on the format of packed color data.

• "type" - the type of pixel data supplied. If you supply an array reference then this is determined automatically. If you supply packed color data this defaults to '8bit', if your data is packed floating point color data then you need to set this to 'float'.

  You can use "float" or "8bit" samples with any image.

  If this is "index" then "pixels" should be either an array of palette color indexes or a packed string of color indexes.

Returns the number of pixels set.

Each of the following sets 5 pixels from (5, 10) through (9, 10) to blue, red, blue, red, blue:

  my $red_color = Imager::Color->new(255, 0, 0);
  my $blue_color = Imager::Color->new(0, 0, 255);

  $image->setscanline(y=>10, x=>5, pixels=>
                      [ ($blue_color, $red_color) x 2, $blue_color ]);

  # use floating point color instead, for 16-bit plus images
  my $red_colorf = Imager::Color::Float->new(1.0, 0, 0);
  my $blue_colorf = Imager::Color::Float->new(0, 0, 1.0);

  $image->setscanline(y=>10, x=>5, pixels=>
                      [ ($blue_colorf, $red_colorf) x 2, $blue_colorf ]);

  # packed 8-bit data
  $image->setscanline(y=>10, x=>5, pixels=>
                      pack("C*", ((0, 0, 255, 255), (255, 0, 0, 255)) x 2,
                            (0, 0, 255, 255)));

  # packed floating point samples
  $image->setscanline(y=>10, x=>5, type=>'float', pixels=>
                      pack("d*", ((0, 0, 1.0, 1.0), (1.0, 0, 0, 1.0)) x 2,
                            (0, 0, 1.0, 1.0)));

Copy even rows from one image to another:

  for (my $y = 0; $y < $im2->getheight; $y+=2) {
    $im1->setscanline(y=>$y,
                      pixels=>scalar($im2->getscanline(y=>$y)));
  }

Set the blue channel to 0 for all pixels in an image. This could be done with convert too:

  for my $y (0..$im->getheight-1) {
    my $row = $im->getscanline(y=>$y);
    $row =~ s/(..).(.)/$1\0$2/gs;
    $im->setscanline(y=>$y, pixels=>$row);
  }

• "y" - vertical position of the scan line. This parameter is required.
• "x" - position to start on the scan line. Default: 0
• "width" - number of pixels to read. Default: $img->getwidth - x
• "type" - the type of pixel data to return. Default: "8bit".

  Permitted values are "8bit" and "float" and "index".

In list context this method will return a list of Imager::Color objects when type is "8bit", or a list of Imager::Color::Float objects when type if "float", or a list of integers when type is "index".

In scalar context this returns a packed 8-bit pixels when type is "8bit", or a list of packed floating point pixels when type is "float", or packed palette color indexes when type is "index".

The values of samples for which the image does not have channels is undefined. For example, for a single channel image the values of channels 1 through 3 are undefined.

Check image for a given color:

  my $found;
  YLOOP: for my $y (0..$img->getheight-1) {
    my @colors = $img->getscanline(y=>$y);
    for my $color (@colors) {
      my ($red, $green, $blue, $alpha) = $color->rgba;
      if ($red == $test_red && $green == $test_green && $blue == $test_blue
          && $alpha == $test_alpha) {
        ++$found;
        last YLOOP;
      }
    }
  }

Or do it using packed data:

  my $found;
  my $test_packed = pack("CCCC", $test_red, $test_green, $test_blue, 
                         $test_alpha);
  YLOOP: for my $y (0..$img->getheight-1) {
    my $colors = $img->getscanline(y=>$y);
    while (length $colors) {
      if (substr($colors, 0, 4, '') eq $test_packed) {
        ++$found;
        last YLOOP;
      }
    }
  }

Some of the examples for "setscanline()" for more examples.

• "y" - vertical position of the scan line. This parameter is required.
• "x" - position to start on the scan line. Default: 0
• "width" - number of pixels to read. Default: "$img->getwidth - x"
• "type" - the type of sample data to return. Default: "8bit".

  Permitted values are "8bit" and "float".

  As of Imager 0.61 this can be "16bit" only for 16 bit images.

• "channels" - a reference to an array of channels to return, where 0 is the first channel. Default: "[ 0 .. $self->getchannels()-1 ]"
• "target" - if an array reference is supplied in target then the samples will be stored here instead of being returned.
• "offset" - the offset within the array referenced by target

In list context this will return a list of integers between 0 and 255 inclusive when type is "8bit", or a list of floating point numbers between 0.0 and 1.0 inclusive when type is "float".

In scalar context this will return a string of packed bytes, as with " pack("C*", ...) " when type is "8bit" or a string of packed doubles as with " pack("d*", ...) " when type is "float".

If the target option is supplied then only a count of samples is returned.

Example: Check if any pixels in an image have a non-zero alpha channel:

  my $has_coverage;
  for my $y (0 .. $img->getheight()-1) {
    my $alpha = $img->getsamples(y=>$y, channels=>[0]);
    if ($alpha =~ /[^\0]/) {
      ++$has_coverage;
      last;
    }
  }

Example: Convert a 2 channel gray image into a 4 channel RGBA image:

  # this could be done with convert() instead
  my $out = Imager->new(xsize => $src->getwidth(), 
                        ysize => $src->getheight(),
                        channels => 4);
  for my $y ( 0 .. $src->getheight()-1 ) {
    my $data = $src->getsamples(y=>$y, channels=>[ 0, 0, 0, 1 ]);
    $out->setscanline(y=>$y, pixels=>$data);
  }

Retrieve 16-bit samples:

  if ($img->bits == 16) {
    my @samples;
    $img->getsamples(x => 0, y => $y, target => \@samples, type => '16bit');
  }

• "y" - vertical position of the scan line. This parameter is required.
• "x" - position to start on the scan line. Default: 0
• "width" - number of pixels to write. Default: "$img->getwidth - x". The minimum of this and the number of pixels represented by the samples provided will be written.
• "type" - the type of sample data to write. This parameter is required.

  This can be "8bit", "float" or for 16-bit images only, "16bit".

• "channels" - a reference to an array of channels to return, where 0 is the first channel. Default: "[ 0 .. $self->getchannels()-1 ]"
• "data" - for a type of "8bit" or "float" this can be a reference to an array of samples or a scalar containing packed samples. If "data" is a scalar it may only contain characters from \x00 to \xFF.

  For a type of "16bit" this can only be a reference to an array of samples to write.

  Required.

• "offset" - the starting offset within the array referenced by data. If "data" is a scalar containing packed samples this offset is in samples.

Returns the number of samples written.

  $targ->setsamples(y => $y, data => \@data);

  $targ->setsamples(y => $y, data => \@data, offset => $src->getchannels);

Copy from one image to another:

  my $targ = Imager->new(xsize => $src->getwidth,
        ysize => $src->getheight, channels => $src->getchannels);
  for my $y (0 .. $targ->getheight()-1) {
    my $row = $src->getsamples(y => $y)
      or die $src->errstr;
    $targ->setsamples(y => $y, data => $row)
      or die $targ->errstr;;
  }

Compose an image from separate source channels:

  my @src = ...; # images to work from, up to 4
  my $targ = Imager->new(xsize => $src[0]->getwidth,
     ysize => $src[0]->getheight, channels => scalar(@src));
  for my $y (0 .. $targ->getheight()-1) {
    for my $ch (0 .. $#src) {
      my $row = $src[$ch]->getsamples(y => $y, channels => [ 0 ]);
      $targ->setsamples(y => $y, data => $row, channels => [ $ch ] );
    }
  }