| Imager::Draw(3pm) | User Contributed Perl Documentation | Imager::Draw(3pm) |
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 anti-aliasing operation all coordinates are rounded towards the nearest integer. For anti-aliased 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 useful to think of "(10, 20)" as "(10.00, 20.00)" and consider the consequences.
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 ]);
While supplying colors as names, array references or CSS color specifiers is convenient, for maximum performance you should supply the color as an Imager::Color object:
my @colors = map Imager::Color->new($_), qw/red green blue/
for my $i (1..1000) {
$image->box(..., color => $colors[rand @colors]);
}
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.
When filling a polygon that overlaps itself, or when filling several polygons with polypolygon() that overlap each other, you can supply a "mode" parameter that controls how the overlap is resolved. This can have one of two possible values:
"nonzero" allows polygons to overlap, either with itself, or with another polygon in the same polypolygon() call, without producing unfilled area in the overlap, and also allows areas to be cut out of the area by specifying the points making up a cut-out in the opposite order.
$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 anti-aliased. 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 multiple 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);
# same as the above points example
my @x = ( 0, 100, 100, 0 );
my @y = ( 0, 0, 100, 100 );
$img->polyline(x => \@x, y => \@y);
$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 omitted it will snap to the outer edge of the image in that direction. If "filled" is omitted 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.
It's also possible to supply a "fill" parameter.
To draw just an arc outline - just the curve, not the radius lines, set filled to 0:
Parameters:
$img->arc(color=>$red, r=>20, x=>200, y=>100, d1=>10, d2=>20, filled=>0 );
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' });
# 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);
$img->circle(color=>$green, r=>50, x=>200, y=>100, aa=>1, filled=>1);
This creates an anti-aliased 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' });
To draw a circular outline, set "filled" to 0:
$img->circle(color=>$green, r=>50, x=>200, y=>100, aa=>1, filled=>0);
$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 anti-aliased, although that will change in the future. Like other anti-aliased 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);
# same as the above points example
my @x = ( 0, 100, 100, 0 );
my @y = ( 0, 0, 100, 100 );
$img->polygon(x => \@x, y => \@y);
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.
$img->polypolygon(points => $points, color => $color);
Draw multiple polygons, either filled or unfilled.
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.
$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:
$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.
You can supply a single set of co-ordinates as scalar "x" and "y" parameters, or set either to an arrayref of ordinates.
If one array is shorter than another the final value in the shorter will be duplicated until they match in length.
If only one of "x" or "y" is an array reference then setpixel() will behave as if the non-reference value were an array reference containing only that value.
eg.
my $count = $img->setpixel(x => 1, y => [ 0 .. 3 ], color => $color);
behaves like:
my $count = $img->setpixel(x => [ 1 ], y => [ 0 .. 3 ], color => $color);
and since the final element in the shorter array is duplicated, this behaves like:
my $count = $img->setpixel(x => [ 1, 1, 1, 1 ], y => [ 0 .. 3 ],
color => $color);
To set an entire or partial row of pixels in one call, consider the "setscanline()" in Imager::Draw or "setsamples()" in Imager::Draw methods.
Parameters:
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:
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.
You can supply a single set of co-ordinates as scalar "x" and "y" parameters, or set each to an arrayref of ordinates.
If one array is shorter than another the final value in the shorter will be duplicated until they match in length.
If only one of "x" or "y" is an array reference then getpixel() will behave as if the non-reference value were an array reference containing only that value.
eg.
my @colors = $img->getpixel(x => 0, y => [ 0 .. 3 ]);
behaves like:
my @colors = $img->getpixel(x => [ 0 ], y => [ 0 .. 3 ]);
and since the final element in the shorter array is duplicated, this behaves like:
my @colors = $img->getpixel(x => [ 0, 0, 0, 0 ], y => [ 0 .. 3 ]);
To receive floating point colors from getpixel(), set the "type" parameter to 'float'.
To retrieve an entire or partial row of pixels, or pixel data, in one call, consider the "getscanline()" in Imager::Draw or "getsamples()" in Imager::Draw methods.
Parameters:
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:
For any of these errors getpixel() returns an empty list.
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:
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.
On error, string() returns false and you can use $img->errstr to get the reason for the error.
# "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:
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.
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);
}
The parameters you can pass are:
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.
The parameters you can pass are:
Permitted values are "8bit" and "float".
As of Imager 0.61 this can be "16bit" only for 16 bit images.
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');
}
Parameters:
This can be "8bit", "float" or for 16-bit images only, "16bit".
For a type of "16bit" this can only be a reference to an array of samples to write.
Required.
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 ] );
}
}
The getscanline() and setscanline() methods 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.
The getsamples() and setsamples() methods can work with samples packed into scalars.
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);
Note that double/sample data is always stored using the C "double" type, never "long double", even if "perl" is built with "-Duselongdouble".
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:
box() does not support anti-aliasing yet. Default color is not unified yet.
Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson.
$Revision$
| 2023-01-11 | perl v5.36.0 |