Imager::Draw - Draw primitives to images

  use Imager;
  use Imager::Fill;

  $img = ...;
  $blue = Imager::Color->new( 0, 0, 255 );
  $fill = Imager::Fill->new(hatch=>'stipple');

  $img->line(color=>$blue, x1=>10, x2=>100,
                           y1=>20, y2=>50, aa=>1, endp=>1 );

  $img->polyline(points=>[[$x0,$y0], [$x1,$y1], [$x2,$y2]],
                 color=>$blue);
  $img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], aa=>1);

  $img->box(color=> $blue, xmin=> 10, ymin=>30,
                           xmax=>200, ymax=>300, filled=>1);
  $img->box(fill=>$fill);

  $img->arc(color=>$blue, r=>20, x=>200, y=>100,
            d1=>10, d2=>20 );

  $img->circle(color=>$blue, r=>50, x=>200, y=>100);

  $img->polygon(points=>[[$x0,$y0], [$x1,$y1], [$x2,$y2]], 
                color=>$blue);

  $img->polygon(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2]);

  $img->flood_fill(x=>50, y=>50, color=>$color);

  $img->setpixel(x=>50, y=>70, color=>$color);

  $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color);

  my $color = $img->getpixel(x=>50, y=>70);

  my @colors = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);

  # drawing text
  my $font = Imager::Font->new(...) or die;
  $img->string(x => 50, y => 70,
               font => $font,
               string => "Hello, World!",
               color => 'red',
               size => 30,
               aa => 1);

  # bottom right-hand corner of the image
  $img->align_string(x => $img->getwidth() - 1,
                     y => $img->getheight() - 1,
                     halign => 'right',
                     valign => 'bottom',
                     string => 'Imager',
                     font => $font,
                     size => 12);

  # low-level functions
  my @colors = $img->getscanline(y=>50, x=>10, width=>20);

  $img->setscanline(y=>60, x=>20, pixels=>\@colors);

  my @samples = $img->getsamples(y=>50, x=>10, width=>20, 
                                 channels=>[ 2, 0 ]);

It is possible to draw with graphics primitives onto images. Such primitives include boxes, arcs, circles, polygons and lines. The coordinate system in Imager has the origin CW(0,0) in the upper left corner of an image. For non antialiasing operation all coordinates are rounded towards the nearest integer. For antialiased operations floating point coordinates are used.

Drawing is assumed to take place in a coordinate system of infinite resolution. This is the typical convention and really only matters when it is necessary to check for off-by-one cases. Typically it's usefull to think of CW(10, 20) as CW(10.00, 20.00) and consider the consiquences.

The CWcolor parameter for any of the drawing methods can be an Imager::Color object, a simple scalar that Imager::Color can understand, a hashref of parameters that Imager::Color->new understands, or an arrayref of red, green, blue values, for example:

  $image->box(..., color=>'red');
  $image->line(..., color=>'#FF0000');
  $image->flood_fill(..., color=>[ 255, 0, 255 ]);

All filled primitives, i.e. CWarc(), CWbox(), CWcircle(), CWpolygon() and the CWflood_fill() method can take a CWfill parameter instead of a CWcolor parameter which can either be an Imager::Fill object, or a reference to a hash containing the parameters used to create the fill, for example:

  $image->box(..., fill=>{ hatch => 'check1x1' });
  my $fillimage = Imager->new;
  $fillimage->read(file=>$somefile) or die;
  $image->flood_fill(..., fill=>{ image=>$fillimage });

Currently you can create opaque or transparent plain color fills, hatched fills, image based fills and fountain fills. See Imager::Fill for more information.

line

  $img->line(color=>$green, x1=>10, x2=>100,
                            y1=>20, y2=>50, aa=>1, endp=>1 );

Draws a line from (x1,y1) to (x2,y2). The endpoint (x2,y2) is drawn by default. If endp of 0 is specified then the endpoint will not be drawn. If CWaa is set then the line will be drawn antialiased. The antialias parameter is still available for backwards compatibility. Parameters:

*

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 drawning a series of connected lines.

*

aa - if true the line is drawn anti-aliased. Default: 0.

polyline

  $img->polyline(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
  $img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], aa=>1);

Polyline is used to draw multilple lines between a series of points. The point set can either be specified as an arrayref to an array of array references (where each such array represents a point). The other way is to specify two array references. The antialias parameter is still available for backwards compatibility.

*

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 CWpoints 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 CWantialias for backward compatibility.

box

  $blue = Imager::Color->new( 0, 0, 255 );
  $img->box(color => $blue, xmin=>10, ymin=>30, xmax=>200, ymax=>300, 
            filled=>1);

If any of the edges of the box are ommited it will snap to the outer edge of the image in that direction. If CWfilled is ommited the box is drawn as an outline. Instead of a color it is possible to use a CWfill pattern:

  $fill = Imager::Fill->new(hatch=>'stipple');
  $img->box(fill=>$fill);  # fill entire image with a given fill pattern

  $img->box(xmin=>10, ymin=>30, xmax=>150, ymax=>60,
            fill => { hatch=>'cross2' });

Also if a color is omitted a color with (255,255,255,255) is used instead. [NOTE: This may change to use CW$img->fgcolor() in the future]. Box does not support fractional coordinates yet. Parameters:

*

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: CW$img->getwidth-1. (right edge of the image)

*

ymax - bottom side of the box. Default: CW$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.

arc

  $img->arc(color=>$red, r=>20, x=>200, y=>100, d1=>10, d2=>20 );

This creates a filled red arc with a 'center' at (200, 100) and spans 10 degrees and the slice has a radius of 20. [NOTE: arc has a BUG in it right now for large differences in angles.] It's also possible to supply a CWfill parameter. 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 CWfill.

*

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.

  # 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' });

circle

  $img->circle(color=>$green, r=>50, x=>200, y=>100, aa=>1, filled=>1);

This creates an antialiased green circle with its center at (200, 100) and has a radius of 50. It's also possible to supply a CWfill parameter instead of a color parameter.

  $img->circle(r => 50, x=> 150, y => 150, fill=>{ hatch => 'stipple' });

The circle is always filled but that might change, so always pass a filled=>1 parameter if you want it to be filled.

*

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 CWfill.

*

fill - the fill for the filled circle. See Fill Parameters

*

aa - if true the filled circle is drawn anti-aliased. Default: false.

polygon

  $img->polygon(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
  $img->polygon(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], fill=>$fill);

Polygon is used to draw a filled polygon. Currently the polygon is always drawn antialiased, although that will change in the future. Like other antialiased drawing functions its coordinates can be specified with floating point values. As with other filled shapes it's possible to use a CWfill instead of a color.

*

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 CWpoints 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 CWfill.

*

fill - the fill for the filled circle. See Fill Parameters

flood_fill

You can fill a region that all has the same color using the flood_fill() method, for example:

  $img->flood_fill(x=>50, y=>50, color=>$color);

will fill all regions the same color connected to the point (50, 50). You can also fill with a complex fill:

  $img->flood_fill(x=>50, y=>50, fill=>{ hatch=>'cross1x1' });

Parameters:

*

x, y - the start point of the fill.

*

color - the color of the filled area. See Color Parameters. Default: white. Overridden by CWfill.

*

fill - the fill for the filled area. See Fill Parameters

setpixel

  $img->setpixel(x=>50, y=>70, color=>$color);
  $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color);

setpixel() is used to set one or more individual pixels. 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.

getpixel

  my $color = $img->getpixel(x=>50, y=>70);
  my @colors = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
  my $colors_ref = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);

getpixel() is used to retrieve one or more individual pixels. For either method you can supply a single set of co-ordinates as scalar x and y parameters, or set each to an arrayref of ordinates. When called with arrays, getpixel() will return a list of colors in list context, and an arrayref in scalar context. To receive floating point colors from getpixel, set the CWtype parameter to 'float'. 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.

*

type - the type of color object to return, either CW'8bit' for Imager::Color objects or CW'float' for Imager::Color::Float objects. Default: CW'8bit'.

string

  my $font = Imager::Font->new(file=>"foo.ttf");
  $img->string(x => 50, y => 70,
               string => "Hello, World!",
               font => $font,
               size => 30,
               aa => 1,
               color => 'white');

Draws text on the image. Parameters:

*

x, y - the point to draw the text from. If CWalign is 0 this is the top left of the string. If CWalign 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 CWtext 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. ie. 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 CWsize.

*

utf8 - for drivers that support it, treat the string as UTF8 encoded. For versions of perl that support Unicode (5.6 and later), this will be enabled automatically if the CWstring parameter is already a UTF8 string. See UTF8 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 CWstring parameter. On error, string() returns false and you can use CW$img->errstr to get the reason for the error.

align_string

Draws text aligned around a point on the image.

  # "Hello" centered at 100, 100 in the image.
  my ($left, $top, $right, $bottom) = 
    $img->align_string(string=>"Hello",
                       x=>100, y=>100, 
                       halign=>'center', valign=>'center', 
                       font=>$font);

Parameters:

*

x, y - the point to draw the text from. If CWalign is 0 this is the top left of the string. If CWalign 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 CWtext 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)

*

top - Point is at the top of the text.

*

bottom - Point is at the bottom of the text.

*

baseline - Point is on the baseline of the text. This is the default.

*

center - Point is vertically centered within the text.

*

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

*

left - The point is at the left of the text. This is the default.

*

start - The point is at the start point of the text.

*

center - The point is horizontally centered within the text.

*

right - The point is at the right end of the text.

*

end - The point is at the end point of the text.

*

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 CWsize.

*

utf8 - for drivers that support it, treat the string as UTF8 encoded. For versions of perl that support Unicode (5.6 and later), this will be enabled automatically if the CWstring parameter is already a UTF8 string. See UTF8 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 CWstring 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 CW$img->errstr to get the reason for the error.

setscanline

Set all or part of a horizontal line of pixels to an image. This method is most useful in conjuction with getscanline. The parameters you can pass are:

*

y - vertical position of the scanline. This parameter is required.

*

x - position to start on the scanline. 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. 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 of object 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 set this to 'float'. You can use float or 8bit samples with any image. 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);
  }

getscanline

Read all or part of a horizonatal line of pixels from an image. This method is most useful in conjunction with setscanline. The parameters you can pass are:

*

y - vertical position of the scanline. This parameter is required.

*

x - position to start on the scanline. Default: 0

*

width - number of pixels to read. Default: CW$img->getwidth - x

*

type - the type of pixel data to return. Default: CW8bit. Permited values are CW8bit and CWfloat. In list context this method will return a list of Imager::Color objects when type is CW8bit, or a list of Imager::Color::Float objects when type if CWfloat. In scalar context this returns a packed 8-bit pixels when type is CW8bit, or a list of packed floating point pixels when type is CWfloat. 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.

getsamples

Read specified channels from all or part of a horizontal line of pixels from an image. The parameters you can pass are:

*

y - vertical position of the scanline. This parameter is required.

*

x - position to start on the scanline. Default: 0

*

width - number of pixels to read. Default: CW$img->getwidth - x

*

type - the type of sample data to return. Default: CW8bit. Permited values are CW8bit and CWfloat.

*

channels - a reference to an array of channels to return, where 0 is the first channel. Default: CW [ 0 .. $self-getchannels()-1 ] > In list context this will return a list of integers between 0 and 255 inclusive when type is CW8bit, or a list of floating point numbers between 0.0 and 1.0 inclusive when type is CWfloat. In scalar context this will return a string of packed bytes, as with CW pack("C*", ...) when type is CW8bit or a string of packed doubles as with CW pack("d*", ...) when type is CWfloat. 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 grey 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);
  }

The getscanline() and setscanline() functions can work with pixels packed into scalars. This is useful to remove the cost of creating color objects, but should only be used when performance is an issue.

Packed data can either be 1 byte per sample or 1 double per sample.

Each pixel returned by getscanline() or supplied to setscanline() contains 4 samples, even if the image has fewer then 4 channels. The values of the extra samples as returned by getscanline() is not specified. The extra samples passed to setscanline() are ignored.

To produce packed 1 byte/sample pixels, use the pack CWC template:

  my $packed_8bit_pixel = pack("CCCC", $red, $blue, $green, $alpha);

To produce packed double/sample pixels, use the pack CWd template:

  my $packed_float_pixel = pack("dddd", $red, $blue, $green, $alpha);

box, arc, do not support antialiasing yet. Arc, is only filled as of yet. Default color is not unified yet.

Tony Cook <tony@imager.perl.org>, Arnar M. Hrafnkelsson.

Imager(3), Imager::Cookbook(3)

$Revision: 875 $