1Imager::Draw(3) User Contributed Perl Documentation Imager::Draw(3)
2
6 Imager::Draw - Draw primitives to images
7
9 use Imager;
10 use Imager::Fill;
11 $img = ...;
13 $blue = Imager::Color->new( 0, 0, 255 );
14 $fill = Imager::Fill->new(hatch=>'stipple');
15 $img->line(color=>$blue, x1=>10, x2=>100,
17 y1=>20, y2=>50, aa=>1, endp=>1 );
18 $img->polyline(points=>[[$x0,$y0], [$x1,$y1], [$x2,$y2]],
20 color=>$blue);
21 $img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], aa=>1);
22 $img->box(color=> $blue, xmin=> 10, ymin=>30,
24 xmax=>200, ymax=>300, filled=>1);
25 $img->box(fill=>$fill);
26 $img->arc(color=>$blue, r=>20, x=>200, y=>100,
28 d1=>10, d2=>20 );
29 $img->circle(color=>$blue, r=>50, x=>200, y=>100);
31 $img->polygon(points=>[[$x0,$y0], [$x1,$y1], [$x2,$y2]],
33 color=>$blue);
34 $img->polygon(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2]);
36 $img->flood_fill(x=>50, y=>50, color=>$color);
38 $img->setpixel(x=>50, y=>70, color=>$color);
40 $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color);
42 my $color = $img->getpixel(x=>50, y=>70);
44 my @colors = $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
46 # drawing text
48 my $font = Imager::Font->new(...) or die;
49 $img->string(x => 50, y => 70,
50 font => $font,
51 string => "Hello, World!",
52 color => 'red',
53 size => 30,
54 aa => 1);
55 # bottom right-hand corner of the image
57 $img->align_string(x => $img->getwidth() - 1,
58 y => $img->getheight() - 1,
59 halign => 'right',
60 valign => 'bottom',
61 string => 'Imager',
62 font => $font,
63 size => 12);
64 # low-level functions
66 my @colors = $img->getscanline(y=>50, x=>10, width=>20);
67 $img->setscanline(y=>60, x=>20, pixels=>\@colors);
69 my @samples = $img->getsamples(y=>50, x=>10, width=>20,
71 channels=>[ 2, 0 ]);
72
74 It is possible to draw with graphics primitives onto images. Such
75 primitives include boxes, arcs, circles, polygons and lines. The
76 coordinate system in Imager has the origin "(0,0)" in the upper left
77 corner of an image with co-ordinates increasing to the right and
78 bottom. For non anti-aliasing operation all coordinates are rounded
79 towards the nearest integer. For anti-aliased operations floating
80 point coordinates are used.
81 Drawing is assumed to take place in a coordinate system of infinite
83 resolution. This is the typical convention and really only matters
84 when it is necessary to check for off-by-one cases. Typically it's
85 useful to think of "(10, 20)" as "(10.00, 20.00)" and consider the
86 consequences.
87 Color Parameters
89 The "color" parameter for any of the drawing methods can be an
90 Imager::Color object, a simple scalar that Imager::Color can
91 understand, a hashref of parameters that Imager::Color->new
92 understands, or an arrayref of red, green, blue values, for example:
93 $image->box(..., color=>'red');
95 $image->line(..., color=>'#FF0000');
96 $image->flood_fill(..., color=>[ 255, 0, 255 ]);
97 While supplying colors as names, array references or CSS color
99 specifiers is convenient, for maximum performance you should supply the
100 color as an Imager::Color object:
101 my @colors = map Imager::Color->new($_), qw/red green blue/
103 for my $i (1..1000) {
104 $image->box(..., color => $colors[rand @colors]);
105 }
106 Fill Parameters
108 All filled primitives, i.e. "arc()", "box()", "circle()", "polygon()"
109 and the "flood_fill()" method can take a "fill" parameter instead of a
110 "color" parameter which can either be an Imager::Fill object, or a
111 reference to a hash containing the parameters used to create the fill,
112 for example:
113 $image->box(..., fill=>{ hatch => 'check1x1' });
115 my $fillimage = Imager->new;
116 $fillimage->read(file=>$somefile) or die;
117 $image->flood_fill(..., fill=>{ image=>$fillimage });
118 Currently you can create opaque or transparent plain color fills,
120 hatched fills, image based fills and fountain fills. See Imager::Fill
121 for more information.
122 Polygon Fill Modes
124 When filling a polygon that overlaps itself, or when filling several
125 polygons with polypolygon() that overlap each other, you can supply a
126 "mode" parameter that controls how the overlap is resolved. This can
127 have one of two possible values:
128 • "evenodd" - if areas overlap an odd number of times, they are
130 filled, and are otherwise unfilled. This is the default and the
131 historical Imager polygon fill mode.
132 • "nonzero" - areas that have an unbalanced clockwise and anti-
134 clockwise boundary are filled. This is the same as "WindingRule"
135 for X and "WINDING" for Win32 GDI.
136 "nonzero" allows polygons to overlap, either with itself, or with
138 another polygon in the same polypolygon() call, without producing
139 unfilled area in the overlap, and also allows areas to be cut out of
140 the area by specifying the points making up a cut-out in the opposite
141 order.
142 List of primitives
144 line()
145 $img->line(color=>$green, x1=>10, x2=>100,
146 y1=>20, y2=>50, aa=>1, endp=>1 );
147 Draws a line from (x1,y1) to (x2,y2). The endpoint (x2,y2) is
149 drawn by default. If "endp" of 0 is specified then the endpoint
150 will not be drawn. If "aa" is set then the line will be drawn
151 anti-aliased. The "antialias" parameter is still available for
152 backwards compatibility.
153 Parameters:
155 • "x1", "y1" - starting point of the line. Required.
157 • "x2", "y2" - end point of the line. Required.
159 • "color" - the color of the line. See "Color Parameters".
161 Default: black.
162 • "endp" - if zero the end point of the line is not drawn.
164 Default: 1 - the end point is drawn. This is useful to set to
165 0 when drawing a series of connected lines.
166 • "aa" - if true the line is drawn anti-aliased. Default: 0.
168 polyline()
170 $img->polyline(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
171 $img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], aa=>1);
172 "polyline" is used to draw multiple lines between a series of
174 points. The point set can either be specified as an arrayref to an
175 array of array references (where each such array represents a
176 point). The other way is to specify two array references.
177 The "antialias" parameter is still available for backwards
179 compatibility.
180 • points - a reference to an array of references to arrays
182 containing the co-ordinates of the points in the line, for
183 example:
184 my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] );
186 $img->polyline(points => \@points);
187 • x, y - each is an array of x or y ordinates. This is an
189 alternative to supplying the "points" parameter.
190 # same as the above points example
192 my @x = ( 0, 100, 100, 0 );
193 my @y = ( 0, 0, 100, 100 );
194 $img->polyline(x => \@x, y => \@y);
195 • "color" - the color of the line. See "Color Parameters".
197 Default: black.
198 • "aa" - if true the line is drawn anti-aliased. Default: 0.
200 Can also be supplied as "antialias" for backward compatibility.
201 box()
203 $blue = Imager::Color->new( 0, 0, 255 );
204 $img->box(color => $blue, xmin=>10, ymin=>30, xmax=>200, ymax=>300,
205 filled=>1);
206 If any of the edges of the box are omitted it will snap to the
208 outer edge of the image in that direction. If "filled" is omitted
209 the box is drawn as an outline. Instead of a color it is possible
210 to use a "fill" pattern:
211 $fill = Imager::Fill->new(hatch=>'stipple');
213 $img->box(fill=>$fill); # fill entire image with a given fill pattern
214 $img->box(xmin=>10, ymin=>30, xmax=>150, ymax=>60,
216 fill => { hatch=>'cross2' });
217 Also if a color is omitted a color with (255,255,255,255) is used
219 instead. [NOTE: This may change to use "$img->fgcolor()" in the
220 future].
221 Box does not support fractional coordinates yet.
223 Parameters:
225 • "xmin" - left side of the box. Default: 0 (left edge of the
227 image)
228 • "ymin" - top side of the box. Default: 0 (top edge of the
230 image)
231 • "xmax" - right side of the box. Default: "$img->getwidth-1".
233 (right edge of the image)
234 • "ymax" - bottom side of the box. Default: "$img->getheight-1".
236 (bottom edge of the image)
237 Note: "xmax" and "ymax" are inclusive - the number of pixels
239 drawn for a filled box is "(xmax-xmin+1) * (ymax-ymin+1)".
240 • "box" - a reference to an array of (left, top, right, bottom)
242 co-ordinates. This is an alternative to supplying "xmin",
243 "ymin", "xmax", "ymax" and overrides their values.
244 • "color" - the color of the line. See "Color Parameters".
246 Default: white. This is ignored if the filled parameter
247 • "filled" - if non-zero the box is filled with color instead of
249 outlined. Default: an outline is drawn.
250 • "fill" - the fill for the box. If this is supplied then the
252 box will be filled. See "Fill Parameters".
253 arc()
255 $img->arc(color=>$red, r=>20, x=>200, y=>100, d1=>10, d2=>20 );
256 This creates a filled red arc with a 'center' at (200, 100) and
258 spans 10 degrees and the slice has a radius of 20.
259 It's also possible to supply a "fill" parameter.
261 To draw just an arc outline - just the curve, not the radius lines,
263 set filled to 0:
264 Parameters:
266 $img->arc(color=>$red, r=>20, x=>200, y=>100, d1=>10, d2=>20, filled=>0 );
268 • "x", "y" - center of the filled arc. Default: center of the
270 image.
271 • "r" - radius of the arc. Default: 1/3 of min(image height,
273 image width).
274 • "d1" - starting angle of the arc, in degrees. Default: 0
276 • "d2" - ending angle of the arc, in degrees. Default: 361.
278 • "color" - the color of the filled arc. See "Color Parameters".
280 Default: white. Overridden by "fill".
281 • "fill" - the fill for the filled arc. See "Fill Parameters"
283 • "aa" - if true the filled arc is drawn anti-aliased. Default:
285 false.
286 Anti-aliased arc() is experimental for now, I'm not entirely
288 happy with the results in some cases.
289 • "filled" - set to 0 to draw only an outline.
291 # arc going through angle zero:
293 $img->arc(d1=>320, d2=>40, x=>100, y=>100, r=>50, color=>'blue');
294 # complex fill arc
296 $img->arc(d1=>135, d2=>45, x=>100, y=>150, r=>50,
297 fill=>{ solid=>'red', combine=>'diff' });
298 # draw an anti-aliased circle outline
300 $img->arc(x => 100, y => 150, r => 150, filled => 0,
301 color => '#F00', aa => 1);
302 # draw an anti-aliased arc
304 $img->arc(x => 100, y => 150, r => 90, filled => 0,
305 color => '#0f0', aa => 1, d1 => 90, d2 => 180);
306 circle()
308 $img->circle(color=>$green, r=>50, x=>200, y=>100, aa=>1, filled=>1);
309 This creates an anti-aliased green circle with its center at (200,
311 100) and has a radius of 50. It's also possible to supply a "fill"
312 parameter instead of a color parameter.
313 $img->circle(r => 50, x=> 150, y => 150, fill=>{ hatch => 'stipple' });
315 To draw a circular outline, set "filled" to 0:
317 $img->circle(color=>$green, r=>50, x=>200, y=>100, aa=>1, filled=>0);
319 • "x", "y" - center of the filled circle. Default: center of the
321 image.
322 • "r" - radius of the circle. Default: 1/3 of min(image height,
324 image width).
325 • "color" - the color of the filled circle. See "Color
327 Parameters". Default: white. Overridden by "fill".
328 • "fill" - the fill for the filled circle. See "Fill Parameters"
330 • "aa" - if true the filled circle is drawn anti-aliased.
332 Default: false.
333 • "filled" - set to 0 to just draw an outline.
335 polygon()
337 $img->polygon(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
338 $img->polygon(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], fill=>$fill);
339 Polygon is used to draw a filled polygon. Currently the polygon is
341 always drawn anti-aliased, although that will change in the future.
342 Like other anti-aliased drawing functions its coordinates can be
343 specified with floating point values. As with other filled shapes
344 it's possible to use a "fill" instead of a color.
345 • "points" - a reference to an array of references to arrays
347 containing the co-ordinates of the points in the line, for
348 example:
349 my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] );
351 $img->polygon(points => \@points);
352 • "x", "y" - each is an array of x or y ordinates. This is an
354 alternative to supplying the "points" parameter.
355 # same as the above points example
357 my @x = ( 0, 100, 100, 0 );
358 my @y = ( 0, 0, 100, 100 );
359 $img->polygon(x => \@x, y => \@y);
360 • "color" - the color of the filled polygon. See "Color
362 Parameters". Default: black. Overridden by "fill".
363 • "fill" - the fill for the filled circle. See "Fill Parameters"
365 • "mode" - fill mode for the polygon. See "Polygon Fill Modes"
367 Note: the points specified are as offsets from the top-left of the
369 image, not as pixel locations. This means that:
370 $img->polygon(points => [ [ 0, 0 ], [ 1, 0 ], [ 1, 1 ], [ 0, 1 ] ]);
372 fills only a single pixel at "(0, 0)", not four.
374 polypolygon()
376 $img->polypolygon(points => $points, color => $color);
377 Draw multiple polygons, either filled or unfilled.
379 • "points" - is an array reference containing polygon
381 definitions, each polygon definition is a reference to an array
382 containing two arrays, one each for the "x" and "y" co-
383 ordinates.
384 • "filled" - if true, fill the polygons with the color defined by
386 "color".
387 • "color" - the color to draw the polygons with if "fill" is not
389 supplied.
390 • "fill" - fill the polygons with this fill if supplied.
392 • "mode" - fill mode for the polygon. See "Polygon Fill Modes"
394 Note: the points specified are as offsets from the top-left of the
396 image, not as pixel locations. This means that:
397 $img->polypolygon(points => [ [ [ 0, 1, 1, 0 ], [ 0, 0, 1, 1 ] ] ],
399 filled => 1);
400 fills only a single pixel at "(0, 0)", not four.
402 flood_fill()
404 You can fill a region that all has the same color using the
405 flood_fill() method, for example:
406 $img->flood_fill(x=>50, y=>50, color=>$color);
408 will fill all regions the same color connected to the point (50,
410 50).
411 Alternatively you can fill a region limited by a given border
413 color:
414 # stop at the red border
416 $im->flood_fill(x=>50, y=>50, color=>$color, border=>"red");
417 You can also fill with a complex fill:
419 $img->flood_fill(x=>50, y=>50, fill=>{ hatch=>'cross1x1' });
421 Parameters:
423 • "x", "y" - the start point of the fill.
425 • "color" - the color of the filled area. See "Color
427 Parameters". Default: white. Overridden by "fill".
428 • "fill" - the fill for the filled area. See "Fill Parameters"
430 • "border" - the border color of the region to be filled. If
432 this parameter is supplied flood_fill() will stop when it finds
433 this color. If this is not supplied then a normal fill is
434 done. "border" can be supplied as a "Color Parameters".
435 setpixel()
437 $img->setpixel(x=>50, y=>70, color=>$color);
438 $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color);
439 setpixel() is used to set one or more individual pixels.
441 You can supply a single set of co-ordinates as scalar "x" and "y"
443 parameters, or set either to an arrayref of ordinates.
444 If one array is shorter than another the final value in the shorter
446 will be duplicated until they match in length.
447 If only one of "x" or "y" is an array reference then setpixel()
449 will behave as if the non-reference value were an array reference
450 containing only that value.
451 eg.
453 my $count = $img->setpixel(x => 1, y => [ 0 .. 3 ], color => $color);
455 behaves like:
457 my $count = $img->setpixel(x => [ 1 ], y => [ 0 .. 3 ], color => $color);
459 and since the final element in the shorter array is duplicated,
461 this behaves like:
462 my $count = $img->setpixel(x => [ 1, 1, 1, 1 ], y => [ 0 .. 3 ],
464 color => $color);
465 To set an entire or partial row of pixels in one call, consider the
467 "setscanline()" in Imager::Draw or "setsamples()" in Imager::Draw
468 methods.
469 Parameters:
471 • x, y - either integers giving the co-ordinates of the pixel to
473 set or array references containing a set of pixels to be set.
474 • color - the color of the pixels drawn. See "Color Parameters".
476 Default: white.
477 Returns the number of pixels drawn, if no pixels were drawn, but
479 none of the errors below occur, returns "0 but true".
480 For other errors, setpixel() returns an empty list and sets
482 errstr().
483 Possible errors conditions include:
485 • the image supplied is empty
487 • a reference to an empty array was supplied for "x" or "y"
489 • "x" or "y" wasn't supplied
491 • "color" isn't a valid color, and can't be converted to a color.
493 getpixel()
495 my $color = $img->getpixel(x=>50, y=>70); my @colors =
496 $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]); my $colors_ref =
497 $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
498 getpixel() is used to retrieve one or more individual pixels.
500 You can supply a single set of co-ordinates as scalar "x" and "y"
502 parameters, or set each to an arrayref of ordinates.
503 If one array is shorter than another the final value in the shorter
505 will be duplicated until they match in length.
506 If only one of "x" or "y" is an array reference then getpixel()
508 will behave as if the non-reference value were an array reference
509 containing only that value.
510 eg.
512 my @colors = $img->getpixel(x => 0, y => [ 0 .. 3 ]);
514 behaves like:
516 my @colors = $img->getpixel(x => [ 0 ], y => [ 0 .. 3 ]);
518 and since the final element in the shorter array is duplicated,
520 this behaves like:
521 my @colors = $img->getpixel(x => [ 0, 0, 0, 0 ], y => [ 0 .. 3 ]);
523 To receive floating point colors from getpixel(), set the "type"
525 parameter to 'float'.
526 To retrieve an entire or partial row of pixels, or pixel data, in
528 one call, consider the "getscanline()" in Imager::Draw or
529 "getsamples()" in Imager::Draw methods.
530 Parameters:
532 • "x", "y" - either integers giving the co-ordinates of the pixel
534 to set or array references containing a set of pixels to be
535 set.
536 • "type" - the type of color object to return, either '8bit' for
538 Imager::Color objects or 'float' for Imager::Color::Float
539 objects. Default: '8bit'.
540 When called with an array reference for either or "x" or "y",
542 getpixel() will return a list of colors in list context, and an
543 arrayref in scalar context.
544 If a supplied co-ordinate is outside the image then "undef" is
546 returned for the pixel.
547 Each color is returned as an Imager::Color object or as an
549 Imager::Color::Float object if "type" is set to "float".
550 Possible errors conditions include:
552 • the image supplied is empty
554 • a reference to an empty array was supplied for "x" or "y"
556 • "x" or "y" wasn't supplied
558 • "type" isn't a valid value.
560 For any of these errors getpixel() returns an empty list.
562 string()
564 my $font = Imager::Font->new(file=>"foo.ttf");
565 $img->string(x => 50, y => 70,
566 string => "Hello, World!",
567 font => $font,
568 size => 30,
569 aa => 1,
570 color => 'white');
571 Draws text on the image.
573 Parameters:
575 • "x", "y" - the point to draw the text from. If "align" is 0
577 this is the top left of the string. If "align" is 1 (the
578 default) then this is the left of the string on the baseline.
579 Required.
580 • "string" - the text to draw. Required unless you supply the
582 "text" parameter.
583 • "font" - an Imager::Font object representing the font to draw
585 the text with. Required.
586 • "aa" - if non-zero the output will be anti-aliased. Default:
588 the value set in Imager::Font->new() or 0 if not set.
589 • "align" - if non-zero the point supplied in (x,y) will be on
591 the base-line, if zero then (x,y) will be at the top-left of
592 the string.
593 i.e. if drawing the string "yA" and align is 0 the point (x,y)
595 will aligned with the top of the A. If align is 1 (the
596 default) it will be aligned with the baseline of the font,
597 typically bottom of the A, depending on the font used.
598 Default: the value set in Imager::Font->new, or 1 if not set.
600 • "channel" - if present, the text will be written to the
602 specified channel of the image and the color parameter will be
603 ignore.
604 • "color" - the color to draw the text in. Default: the color
606 supplied to Imager::Font->new, or red if none.
607 • "size" - the point size to draw the text at. Default: the size
609 supplied to Imager::Font->new, or 15.
610 • "sizew" - the width scaling to draw the text at. Default: the
612 value of "size".
613 • "utf8" - for drivers that support it, treat the string as UTF-8
615 encoded. For versions of perl that support Unicode (5.6 and
616 later), this will be enabled automatically if the "string"
617 parameter is already a UTF-8 string. See "UTF-8" in
618 Imager::Font for more information.
619 • "vlayout" - for drivers that support it, draw the text
621 vertically. Note: I haven't found a font that has the
622 appropriate metrics yet.
623 • "text" - alias for the "string" parameter.
625 On error, string() returns false and you can use $img->errstr to
627 get the reason for the error.
628 align_string()
630 Draws text aligned around a point on the image.
631 # "Hello" centered at 100, 100 in the image.
633 my ($left, $top, $right, $bottom) =
634 $img->align_string(string=>"Hello",
635 x=>100, y=>100,
636 halign=>'center', valign=>'center',
637 font=>$font);
638 Parameters:
640 • "x", "y" - the point to draw the text from. If "align" is 0
642 this is the top left of the string. If "align" is 1 (the
643 default) then this is the left of the string on the baseline.
644 Required.
645 • "string" - the text to draw. Required unless you supply the
647 "text" parameter.
648 • "font" - an Imager::Font object representing the font to draw
650 the text with. Required.
651 • "aa" - if non-zero the output will be anti-aliased
653 • "valign" - vertical alignment of the text against (x,y)
655 • "top" - Point is at the top of the text.
657 • "bottom" - Point is at the bottom of the text.
659 • "baseline" - Point is on the baseline of the text. This is
661 the default.
662 • "center" - Point is vertically centered within the text.
664 • "halign" - horizontal alignment of the text against (x,y)
666 • "left" - The point is at the left of the text. This is the
668 default.
669 • "start" - The point is at the start point of the text.
671 • "center" - The point is horizontally centered within the
673 text.
674 • "right" - The point is at the right end of the text.
676 • "end" - The point is at the end point of the text.
678 • "channel" - if present, the text will be written to the
680 specified channel of the image and the color parameter will be
681 ignore.
682 • "color" - the color to draw the text in. Default: the color
684 supplied to Imager::Font->new, or red if none.
685 • "size" - the point size to draw the text at. Default: the size
687 supplied to Imager::Font->new, or 15.
688 • "sizew" - the width scaling to draw the text at. Default: the
690 value of "size".
691 • "utf8" - for drivers that support it, treat the string as UTF-8
693 encoded. For versions of perl that support Unicode (5.6 and
694 later), this will be enabled automatically if the "string"
695 parameter is already a UTF-8 string. See "UTF-8" in
696 Imager::Font for more information.
697 • "vlayout" - for drivers that support it, draw the text
699 vertically. Note: I haven't found a font that has the
700 appropriate metrics yet.
701 • "text" - alias for the "string" parameter.
703 On success returns a list of bounds of the drawn text, in the order
705 left, top, right, bottom.
706 On error, align_string() returns an empty list and you can use
708 "$img->errstr" to get the reason for the error.
709 setscanline()
711 Set all or part of a horizontal line of pixels to an image. This
712 method is most useful in conjunction with "getscanline()".
713 The parameters you can pass are:
715 • "y" - vertical position of the scan line. This parameter is
717 required.
718 • "x" - position to start on the scan line. Default: 0
720 • "pixels" - either a reference to an array containing
722 Imager::Color objects, an reference to an array containing
723 Imager::Color::Float objects or a scalar containing packed
724 color data.
725 If "type" is "index" then this can either be a reference to an
727 array of palette color indexes or a scalar containing packed
728 indexes.
729 See "Packed Color Data" for information on the format of packed
731 color data.
732 • "type" - the type of pixel data supplied. If you supply an
734 array reference then this is determined automatically. If you
735 supply packed color data this defaults to '8bit', if your data
736 is packed floating point color data then you need to set this
737 to 'float'.
738 You can use "float" or "8bit" samples with any image.
740 If this is "index" then "pixels" should be either an array of
742 palette color indexes or a packed string of color indexes.
743 Returns the number of pixels set.
745 Each of the following sets 5 pixels from (5, 10) through (9, 10) to
747 blue, red, blue, red, blue:
748 my $red_color = Imager::Color->new(255, 0, 0);
750 my $blue_color = Imager::Color->new(0, 0, 255);
751 $image->setscanline(y=>10, x=>5, pixels=>
753 [ ($blue_color, $red_color) x 2, $blue_color ]);
754 # use floating point color instead, for 16-bit plus images
756 my $red_colorf = Imager::Color::Float->new(1.0, 0, 0);
757 my $blue_colorf = Imager::Color::Float->new(0, 0, 1.0);
758 $image->setscanline(y=>10, x=>5, pixels=>
760 [ ($blue_colorf, $red_colorf) x 2, $blue_colorf ]);
761 # packed 8-bit data
763 $image->setscanline(y=>10, x=>5, pixels=>
764 pack("C*", ((0, 0, 255, 255), (255, 0, 0, 255)) x 2,
765 (0, 0, 255, 255)));
766 # packed floating point samples
768 $image->setscanline(y=>10, x=>5, type=>'float', pixels=>
769 pack("d*", ((0, 0, 1.0, 1.0), (1.0, 0, 0, 1.0)) x 2,
770 (0, 0, 1.0, 1.0)));
771 Copy even rows from one image to another:
773 for (my $y = 0; $y < $im2->getheight; $y+=2) {
775 $im1->setscanline(y=>$y,
776 pixels=>scalar($im2->getscanline(y=>$y)));
777 }
778 Set the blue channel to 0 for all pixels in an image. This could
780 be done with convert too:
781 for my $y (0..$im->getheight-1) {
783 my $row = $im->getscanline(y=>$y);
784 $row =~ s/(..).(.)/$1\0$2/gs;
785 $im->setscanline(y=>$y, pixels=>$row);
786 }
787 getscanline()
789 Read all or part of a horizontal line of pixels from an image.
790 This method is most useful in conjunction with "setscanline()".
791 The parameters you can pass are:
793 • "y" - vertical position of the scan line. This parameter is
795 required.
796 • "x" - position to start on the scan line. Default: 0
798 • "width" - number of pixels to read. Default: $img->getwidth -
800 x
801 • "type" - the type of pixel data to return. Default: "8bit".
803 Permitted values are "8bit" and "float" and "index".
805 In list context this method will return a list of Imager::Color
807 objects when type is "8bit", or a list of Imager::Color::Float
808 objects when type if "float", or a list of integers when type is
809 "index".
810 In scalar context this returns a packed 8-bit pixels when type is
812 "8bit", or a list of packed floating point pixels when type is
813 "float", or packed palette color indexes when type is "index".
814 The values of samples for which the image does not have channels is
816 undefined. For example, for a single channel image the values of
817 channels 1 through 3 are undefined.
818 Check image for a given color:
820 my $found;
822 YLOOP: for my $y (0..$img->getheight-1) {
823 my @colors = $img->getscanline(y=>$y);
824 for my $color (@colors) {
825 my ($red, $green, $blue, $alpha) = $color->rgba;
826 if ($red == $test_red && $green == $test_green && $blue == $test_blue
827 && $alpha == $test_alpha) {
828 ++$found;
829 last YLOOP;
830 }
831 }
832 }
833 Or do it using packed data:
835 my $found;
837 my $test_packed = pack("CCCC", $test_red, $test_green, $test_blue,
838 $test_alpha);
839 YLOOP: for my $y (0..$img->getheight-1) {
840 my $colors = $img->getscanline(y=>$y);
841 while (length $colors) {
842 if (substr($colors, 0, 4, '') eq $test_packed) {
843 ++$found;
844 last YLOOP;
845 }
846 }
847 }
848 Some of the examples for "setscanline()" for more examples.
850 getsamples()
852 Read specified channels from all or part of a horizontal line of
853 pixels from an image.
854 The parameters you can pass are:
856 • "y" - vertical position of the scan line. This parameter is
858 required.
859 • "x" - position to start on the scan line. Default: 0
861 • "width" - number of pixels to read. Default: "$img->getwidth -
863 x"
864 • "type" - the type of sample data to return. Default: "8bit".
866 Permitted values are "8bit" and "float".
868 As of Imager 0.61 this can be "16bit" only for 16 bit images.
870 • "channels" - a reference to an array of channels to return,
872 where 0 is the first channel. Default: "[ 0 ..
873 $self->getchannels()-1 ]"
874 • "target" - if an array reference is supplied in target then the
876 samples will be stored here instead of being returned.
877 • "offset" - the offset within the array referenced by target
879 In list context this will return a list of integers between 0 and
881 255 inclusive when type is "8bit", or a list of floating point
882 numbers between 0.0 and 1.0 inclusive when type is "float".
883 In scalar context this will return a string of packed bytes, as
885 with " pack("C*", ...) " when type is "8bit" or a string of packed
886 doubles as with " pack("d*", ...) " when type is "float".
887 If the target option is supplied then only a count of samples is
889 returned.
890 Example: Check if any pixels in an image have a non-zero alpha
892 channel:
893 my $has_coverage;
895 for my $y (0 .. $img->getheight()-1) {
896 my $alpha = $img->getsamples(y=>$y, channels=>[0]);
897 if ($alpha =~ /[^\0]/) {
898 ++$has_coverage;
899 last;
900 }
901 }
902 Example: Convert a 2 channel gray image into a 4 channel RGBA
904 image:
905 # this could be done with convert() instead
907 my $out = Imager->new(xsize => $src->getwidth(),
908 ysize => $src->getheight(),
909 channels => 4);
910 for my $y ( 0 .. $src->getheight()-1 ) {
911 my $data = $src->getsamples(y=>$y, channels=>[ 0, 0, 0, 1 ]);
912 $out->setscanline(y=>$y, pixels=>$data);
913 }
914 Retrieve 16-bit samples:
916 if ($img->bits == 16) {
918 my @samples;
919 $img->getsamples(x => 0, y => $y, target => \@samples, type => '16bit');
920 }
921 setsamples()
923 This allows writing of samples to an image.
924 Parameters:
926 • "y" - vertical position of the scan line. This parameter is
928 required.
929 • "x" - position to start on the scan line. Default: 0
931 • "width" - number of pixels to write. Default: "$img->getwidth
933 - x". The minimum of this and the number of pixels represented
934 by the samples provided will be written.
935 • "type" - the type of sample data to write. This parameter is
937 required.
938 This can be "8bit", "float" or for 16-bit images only, "16bit".
940 • "channels" - a reference to an array of channels to return,
942 where 0 is the first channel. Default: "[ 0 ..
943 $self->getchannels()-1 ]"
944 • "data" - for a type of "8bit" or "float" this can be a
946 reference to an array of samples or a scalar containing packed
947 samples. If "data" is a scalar it may only contain characters
948 from \x00 to \xFF.
949 For a type of "16bit" this can only be a reference to an array
951 of samples to write.
952 Required.
954 • "offset" - the starting offset within the array referenced by
956 data. If "data" is a scalar containing packed samples this
957 offset is in samples.
958 Returns the number of samples written.
960 $targ->setsamples(y => $y, data => \@data);
962 $targ->setsamples(y => $y, data => \@data, offset => $src->getchannels);
964 Copy from one image to another:
966 my $targ = Imager->new(xsize => $src->getwidth,
968 ysize => $src->getheight, channels => $src->getchannels);
969 for my $y (0 .. $targ->getheight()-1) {
970 my $row = $src->getsamples(y => $y)
971 or die $src->errstr;
972 $targ->setsamples(y => $y, data => $row)
973 or die $targ->errstr;;
974 }
975 Compose an image from separate source channels:
977 my @src = ...; # images to work from, up to 4
979 my $targ = Imager->new(xsize => $src[0]->getwidth,
980 ysize => $src[0]->getheight, channels => scalar(@src));
981 for my $y (0 .. $targ->getheight()-1) {
982 for my $ch (0 .. $#src) {
983 my $row = $src[$ch]->getsamples(y => $y, channels => [ 0 ]);
984 $targ->setsamples(y => $y, data => $row, channels => [ $ch ] );
985 }
986 }
987
989 The getscanline() and setscanline() methods can work with pixels packed
990 into scalars. This is useful to remove the cost of creating color
991 objects, but should only be used when performance is an issue.
992 The getsamples() and setsamples() methods can work with samples packed
994 into scalars.
995 Packed data can either be 1 byte per sample or 1 double per sample.
997 Each pixel returned by getscanline() or supplied to setscanline()
999 contains 4 samples, even if the image has fewer then 4 channels. The
1000 values of the extra samples as returned by getscanline() is not
1001 specified. The extra samples passed to setscanline() are ignored.
1002 To produce packed 1 byte/sample pixels, use the pack "C" template:
1004 my $packed_8bit_pixel = pack("CCCC", $red, $blue, $green, $alpha);
1006 To produce packed double/sample pixels, use the pack "d" template:
1008 my $packed_float_pixel = pack("dddd", $red, $blue, $green, $alpha);
1010 Note that double/sample data is always stored using the C "double"
1012 type, never "long double", even if "perl" is built with
1013 "-Duselongdouble".
1014 If you use a type parameter of "index" then the values are palette
1016 color indexes, not sample values:
1017 my $im = Imager->new(xsize => 100, ysize => 100, type => 'paletted');
1019 my $black_index = $im->addcolors(colors => [ 'black' ]);
1020 my $red_index = $im->addcolors(colors => [ 'red' ]);
1021 # 2 pixels
1022 my $packed_index_data = pack("C*", $black_index, $red_index);
1023 $im->setscanline(y => $y, pixels => $packed_index_data, type => 'index');
1024
1026 Some methods accept a "combine" parameter, this can be any of the
1027 following:
1028 "none"
1030 The fill pixel replaces the target pixel.
1031 "normal"
1033 The fill pixels alpha value is used to combine it with the target
1034 pixel.
1035 "multiply"
1037 "mult"
1038 Each channel of fill and target is multiplied, and the result is
1039 combined using the alpha channel of the fill pixel.
1040 "dissolve"
1042 If the alpha of the fill pixel is greater than a random number, the
1043 fill pixel is alpha combined with the target pixel.
1044 "add"
1046 The channels of the fill and target are added together, clamped to
1047 the range of the samples and alpha combined with the target.
1048 "subtract"
1050 The channels of the fill are subtracted from the target, clamped to
1051 be >= 0, and alpha combined with the target.
1052 "diff"
1054 The channels of the fill are subtracted from the target and the
1055 absolute value taken this is alpha combined with the target.
1056 "lighten"
1058 The higher value is taken from each channel of the fill and target
1059 pixels, which is then alpha combined with the target.
1060 "darken"
1062 The higher value is taken from each channel of the fill and target
1063 pixels, which is then alpha combined with the target.
1064 "hue"
1066 The combination of the saturation and value of the target is
1067 combined with the hue of the fill pixel, and is then alpha combined
1068 with the target.
1069 "sat"
1071 The combination of the hue and value of the target is combined with
1072 the saturation of the fill pixel, and is then alpha combined with
1073 the target.
1074 "value"
1076 The combination of the hue and value of the target is combined with
1077 the value of the fill pixel, and is then alpha combined with the
1078 target.
1079 "color"
1081 The combination of the value of the target is combined with the hue
1082 and saturation of the fill pixel, and is then alpha combined with
1083 the target.
1084 combines()
1086 Returns a list of possible combine types.
1087
1089 box() does not support anti-aliasing yet. Default color is not unified
1090 yet.
1091
1093 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson.
1094
1096 Imager(3), Imager::Cookbook(3)
1097
1099 $Revision$
1100perl v5.36.0 2022-07-22 Imager::Draw(3)