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 (0,0) in the upper left corner of an image with co-ordinates increasing to the right and bottom. 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.
$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.
Parameters:
$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.
my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] ); $img->polyline(points => \@points);
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);
antialias for backward compatibility. $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.
Parameters:
Note: xmax and ymax are inclusive - the number of pixels drawn for a filled box is (xmax-xmin+1) * (ymax-ymin+1).
$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.
Parameters:
fill.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' });
$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 fill 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.
fill.$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.
my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] ); $img->polygon(points => \@points);
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);
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).
Alternatively you can fill a region limited by a given border color:
# stop at the red border $im->flood_fill(x=>50, y=>50, color=>$color, border=>"red");
You can also fill with a complex fill:
$img->flood_fill(x=>50, y=>50, fill=>{ hatch=>'cross1x1' });
Parameters:
fill.border can be supplied as a "Color Parameter".$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:
When called with array parameters, returns the number of pixels successfully set, or false if none.
When called with scalars for x and y, return $img on success, false on failure.
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 type parameter to 'float'.
Parameters:
'8bit' for Imager::Color objects or 'float' for Imager::Color::Float objects. Default: '8bit'. 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:
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.text parameter.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.
size.string parameter is already a UTF8 string. See "UTF8" in Imager::Font for more information.string parameter.On error, string() returns false and you can use $img->errstr to get the reason for the error.
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:
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.text parameter.size.string parameter is already a UTF8 string. See "UTF8" in Imager::Font for more information.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.
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:
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.
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);
}
Read all or part of a horizontal line of pixels from an image. This method is most useful in conjunction with "setscanline".
The parameters you can pass are:
8bit.
Permited 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.
Read specified channels from all or part of a horizontal line of pixels from an image.
The parameters you can pass are:
8bit.
Permited values are 8bit and float.
As of Imager 0.61 this can be 16bit only for 16 bit images.
[ 0 .. $self-getchannels()-1 ] >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 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);
}
Retrieve 16-bit samples:
if ($img->bits == 16) {
my @samples;
$img->getsamples(x => 0, y => $y, target => \@samples, type => '16bit');
}
This allows writing of samples back to some images. Currently this is only supported for 16-bit/sample images.
Parameters:
As of Imager 0.61 this can only be 16bit only for 16 bit images.
[ 0 .. $self-getchannels()-1 ] >Returns the number of samples written.
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 C template:
my $packed_8bit_pixel = pack("CCCC", $red, $blue, $green, $alpha);
To produce packed double/sample pixels, use the pack d template:
my $packed_float_pixel = pack("dddd", $red, $blue, $green, $alpha);
If you use a type parameter of index then the values are palette color indexes, not sample values:
my $im = Imager->new(xsize => 100, ysize => 100, type => 'paletted');
my $black_index = $im->addcolors(colors => [ 'black' ]);
my $red_index = $im->addcolors(colors => [ 'red' ]);
# 2 pixels
my $packed_index_data = pack("C*", $black_index, $red_index);
$im->setscanline(y => $y, pixels => $packed_index_data, type => 'index');
Some methods accept a combine parameter, this can be any of the following:
The fill pixel replaces the target pixel.
The fill pixels alpha value is used to combine it with the target pixel.
Each channel of fill and target is multiplied, and the result is combined using the alpha channel of the fill pixel.
If the alpha of the fill pixel is greater than a random number, the fill pixel is alpha combined with the target pixel.
The channels of the fill and target are added together, clamped to the range of the samples and alpha combined with the target.
The channels of the fill are subtracted from the target, clamped to be >= 0, and alpha combined with the target.
The channels of the fill are subtracted from the target and the absolute value taken this is alpha combined with the target.
The higher value is taken from each channel of the fill and target pixels, which is then alpha combined with the target.
The higher value is taken from each channel of the fill and target pixels, which is then alpha combined with the target.
The combination of the saturation and value of the target is combined with the hue of the fill pixel, and is then alpha combined with the target.
The combination of the hue and value of the target is combined with the saturation of the fill pixel, and is then alpha combined with the target.
The combination of the hue and value of the target is combined with the value of the fill pixel, and is then alpha combined with the target.
The combination of the value of the target is combined with the hue and saturation of the fill pixel, and is then alpha combined with the target.
Returns a list of possible combine types.
box() does 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: 1465 $
