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]);
# 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 ]);
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
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.
Color Parameters¶
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]);
}
Fill Parameters¶
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
anti-aliased. 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 drawing 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 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.
- •
- 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.
- 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 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:
- •
- "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".
- 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.
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 );
- •
- "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);
- circle()
-
$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);
- •
- "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.
- 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 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.
- •
- "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"
- 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).
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:
- •
- "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".
- 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.
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);
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.
When called with an array reference in either "x" or "y",
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.
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.
On any of these errors,
setpixel() returns an empty list and sets
errstr().
- 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.
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'.
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 '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.
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.
- 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 "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.
- 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 "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)
- •
- "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 "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.
- setscanline()
- Set all or part of a horizontal line of pixels to an image.
This method is most useful in conjunction with "
getscanline()".
The parameters you can pass are:
- •
- "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 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.
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);
}
- getscanline()
- 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:
- •
- "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.
- 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 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');
}
- setsamples()
- This allows writing of samples back to some images.
Currently this is only supported for 16-bit/sample images.
Parameters:
- •
- "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 ] );
}
}
Packed Color Data¶
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);
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');
Combine Types¶
Some methods accept a "combine" parameter, this can be any of the
following:
- "none"
- The fill pixel replaces the target pixel.
- "normal"
- The fill pixels alpha value is used to combine it with the
target pixel.
- "multiply"
- "mult"
- Each channel of fill and target is multiplied, and the
result is combined using the alpha channel of the fill pixel.
- "dissolve"
- If the alpha of the fill pixel is greater than a random
number, the fill pixel is alpha combined with the target pixel.
- "add"
- The channels of the fill and target are added together,
clamped to the range of the samples and alpha combined with the
target.
- "subtract"
- The channels of the fill are subtracted from the target,
clamped to be >= 0, and alpha combined with the target.
- "diff"
- The channels of the fill are subtracted from the target and
the absolute value taken this is alpha combined with the target.
- "lighten"
- The higher value is taken from each channel of the fill and
target pixels, which is then alpha combined with the target.
- "darken"
- The higher value is taken from each channel of the fill and
target pixels, which is then alpha combined with the target.
- "hue"
- 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.
- "sat"
- 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.
- "value"
- 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.
- "color"
- 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.
- combines()
- Returns a list of possible combine types.
BUGS¶
box() does not support anti-aliasing yet. Default color is not unified
yet.
AUTHOR¶
Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson.
SEE ALSO¶
Imager(3), Imager::Cookbook(3)
REVISION¶
$Revision$
