Imager::Draw - Draw primitives to images |
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 the Imager::Color manpage 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 the Imager::Color manpage 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 the Imager::Fill manpage 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:
evenodd
- if areas overlap an odd number of times, they are filled,
and are otherwise unfilled. This is the default and the historical
Imager polygon fill mode.
nonzero
- areas that have an unbalanced clockwise and
anti-clockwise boundary are filled. This is the same as
WindingRule
for X and WINDING
for Win32 GDI.
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.
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.
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);
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
mode
- fill mode for the polygon. See Polygon Fill Modes
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.
polypolygon()
$img->polypolygon(points => $points, color => $color);
Draw multiple polygons, either filled or unfilled.
points
- is an array reference containing polygon definitions, each
polygon definition is a reference to an array containing two arrays,
one each for the x
and y
co-ordinates.
filled
- if true, fill the polygons with the color defined by
color
.
color
- the color to draw the polygons with if fill
is not
supplied.
fill
- fill the polygons with this fill if supplied.
mode
- fill mode for the polygon. See Polygon Fill Modes
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.
flood_fill()
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:
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:
x
or y
x
or y
wasn't suppliedcolor
isn't a valid color, and can't be converted to a
color.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
the Imager::Color manpage objects or 'float'
for the Imager::Color::Float manpage
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.
Each color is returned as an the Imager::Color manpage object or as an
the Imager::Color::Float manpage object if type
is set to "float"
.
Possible errors conditions include:
x
or y
x
or y
wasn't suppliedtype
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 the Imager::Font manpage 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 the Imager::Font manpage 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()
# "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 the Imager::Font manpage 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 the Imager::Font manpage 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()
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 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 you need to 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()
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()
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()
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 ] ); } }
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:
none
normal
multiply
mult
dissolve
add
subtract
diff
lighten
darken
hue
sat
value
color
combines()
box()
does not support anti-aliasing yet. Default color is not
unified yet.
Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson.
Imager(3), the Imager::Cookbook manpage(3)
$Revision$
Imager::Draw - Draw primitives to images |