NAME

Imager::Draw - Draw primitives to images

SYNOPSIS

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]);

DESCRIPTION

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 (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 (10, 20) as (10.00, 20.00) and consider the consiquences.

The color 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. arc(), box(), circle(), polygon() and the flood_fill() method can take a fill parameter instead of a color 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.

List of primitives

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 aa is set then the line will be drawn antialiased. The antialias parameter is still available for backwards compatibility.

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.

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 filled is ommited the box is drawn as an outline. Instead of a color it is possible to use a fill 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 $img->fgcolor() in the future].

Box does not support fractional coordinates yet.

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 fill parameter.

circle

$img->circle(color=>$green, r=>50, x=>200, y=>100, aa=>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 fill parameter instead of a color parameter.

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

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 fill instead of a color.

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

setpixel and getpixel

$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]);

setpixel() is used to set one or more individual pixels, and getpixel() to retrieve the same.

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 type parameter to 'float'.

BUGS

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

SEE ALSO

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