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 Parameters:
467 • x, y - either integers giving the co-ordinates of the pixel to
469 set or array references containing a set of pixels to be set.
470 • color - the color of the pixels drawn. See "Color Parameters".
472 Default: white.
473 Returns the number of pixels drawn, if no pixels were drawn, but
475 none of the errors below occur, returns "0 but true".
476 For other errors, setpixel() returns an empty list and sets
478 errstr().
479 Possible errors conditions include:
481 • the image supplied is empty
483 • a reference to an empty array was supplied for "x" or "y"
485 • "x" or "y" wasn't supplied
487 • "color" isn't a valid color, and can't be converted to a color.
489 getpixel()
491 my $color = $img->getpixel(x=>50, y=>70); my @colors =
492 $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]); my $colors_ref =
493 $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
494 getpixel() is used to retrieve one or more individual pixels.
496 You can supply a single set of co-ordinates as scalar "x" and "y"
498 parameters, or set each to an arrayref of ordinates.
499 If one array is shorter than another the final value in the shorter
501 will be duplicated until they match in length.
502 If only one of "x" or "y" is an array reference then getpixel()
504 will behave as if the non-reference value were an array reference
505 containing only that value.
506 eg.
508 my @colors = $img->getpixel(x => 0, y => [ 0 .. 3 ]);
510 behaves like:
512 my @colors = $img->getpixel(x => [ 0 ], y => [ 0 .. 3 ]);
514 and since the final element in the shorter array is duplicated,
516 this behaves like:
517 my @colors = $img->getpixel(x => [ 0, 0, 0, 0 ], y => [ 0 .. 3 ]);
519 To receive floating point colors from getpixel(), set the "type"
521 parameter to 'float'.
522 Parameters:
524 • "x", "y" - either integers giving the co-ordinates of the pixel
526 to set or array references containing a set of pixels to be
527 set.
528 • "type" - the type of color object to return, either '8bit' for
530 Imager::Color objects or 'float' for Imager::Color::Float
531 objects. Default: '8bit'.
532 When called with an array reference for either or "x" or "y",
534 getpixel() will return a list of colors in list context, and an
535 arrayref in scalar context.
536 If a supplied co-ordinate is outside the image then "undef" is
538 returned for the pixel.
539 Each color is returned as an Imager::Color object or as an
541 Imager::Color::Float object if "type" is set to "float".
542 Possible errors conditions include:
544 • the image supplied is empty
546 • a reference to an empty array was supplied for "x" or "y"
548 • "x" or "y" wasn't supplied
550 • "type" isn't a valid value.
552 For any of these errors getpixel() returns an empty list.
554 string()
556 my $font = Imager::Font->new(file=>"foo.ttf");
557 $img->string(x => 50, y => 70,
558 string => "Hello, World!",
559 font => $font,
560 size => 30,
561 aa => 1,
562 color => 'white');
563 Draws text on the image.
565 Parameters:
567 • "x", "y" - the point to draw the text from. If "align" is 0
569 this is the top left of the string. If "align" is 1 (the
570 default) then this is the left of the string on the baseline.
571 Required.
572 • "string" - the text to draw. Required unless you supply the
574 "text" parameter.
575 • "font" - an Imager::Font object representing the font to draw
577 the text with. Required.
578 • "aa" - if non-zero the output will be anti-aliased. Default:
580 the value set in Imager::Font->new() or 0 if not set.
581 • "align" - if non-zero the point supplied in (x,y) will be on
583 the base-line, if zero then (x,y) will be at the top-left of
584 the string.
585 i.e. if drawing the string "yA" and align is 0 the point (x,y)
587 will aligned with the top of the A. If align is 1 (the
588 default) it will be aligned with the baseline of the font,
589 typically bottom of the A, depending on the font used.
590 Default: the value set in Imager::Font->new, or 1 if not set.
592 • "channel" - if present, the text will be written to the
594 specified channel of the image and the color parameter will be
595 ignore.
596 • "color" - the color to draw the text in. Default: the color
598 supplied to Imager::Font->new, or red if none.
599 • "size" - the point size to draw the text at. Default: the size
601 supplied to Imager::Font->new, or 15.
602 • "sizew" - the width scaling to draw the text at. Default: the
604 value of "size".
605 • "utf8" - for drivers that support it, treat the string as UTF-8
607 encoded. For versions of perl that support Unicode (5.6 and
608 later), this will be enabled automatically if the "string"
609 parameter is already a UTF-8 string. See "UTF-8" in
610 Imager::Font for more information.
611 • "vlayout" - for drivers that support it, draw the text
613 vertically. Note: I haven't found a font that has the
614 appropriate metrics yet.
615 • "text" - alias for the "string" parameter.
617 On error, string() returns false and you can use $img->errstr to
619 get the reason for the error.
620 align_string()
622 Draws text aligned around a point on the image.
623 # "Hello" centered at 100, 100 in the image.
625 my ($left, $top, $right, $bottom) =
626 $img->align_string(string=>"Hello",
627 x=>100, y=>100,
628 halign=>'center', valign=>'center',
629 font=>$font);
630 Parameters:
632 • "x", "y" - the point to draw the text from. If "align" is 0
634 this is the top left of the string. If "align" is 1 (the
635 default) then this is the left of the string on the baseline.
636 Required.
637 • "string" - the text to draw. Required unless you supply the
639 "text" parameter.
640 • "font" - an Imager::Font object representing the font to draw
642 the text with. Required.
643 • "aa" - if non-zero the output will be anti-aliased
645 • "valign" - vertical alignment of the text against (x,y)
647 • "top" - Point is at the top of the text.
649 • "bottom" - Point is at the bottom of the text.
651 • "baseline" - Point is on the baseline of the text. This is
653 the default.
654 • "center" - Point is vertically centered within the text.
656 • "halign" - horizontal alignment of the text against (x,y)
658 • "left" - The point is at the left of the text. This is the
660 default.
661 • "start" - The point is at the start point of the text.
663 • "center" - The point is horizontally centered within the
665 text.
666 • "right" - The point is at the right end of the text.
668 • "end" - The point is at the end point of the text.
670 • "channel" - if present, the text will be written to the
672 specified channel of the image and the color parameter will be
673 ignore.
674 • "color" - the color to draw the text in. Default: the color
676 supplied to Imager::Font->new, or red if none.
677 • "size" - the point size to draw the text at. Default: the size
679 supplied to Imager::Font->new, or 15.
680 • "sizew" - the width scaling to draw the text at. Default: the
682 value of "size".
683 • "utf8" - for drivers that support it, treat the string as UTF-8
685 encoded. For versions of perl that support Unicode (5.6 and
686 later), this will be enabled automatically if the "string"
687 parameter is already a UTF-8 string. See "UTF-8" in
688 Imager::Font for more information.
689 • "vlayout" - for drivers that support it, draw the text
691 vertically. Note: I haven't found a font that has the
692 appropriate metrics yet.
693 • "text" - alias for the "string" parameter.
695 On success returns a list of bounds of the drawn text, in the order
697 left, top, right, bottom.
698 On error, align_string() returns an empty list and you can use
700 "$img->errstr" to get the reason for the error.
701 setscanline()
703 Set all or part of a horizontal line of pixels to an image. This
704 method is most useful in conjunction with "getscanline()".
705 The parameters you can pass are:
707 • "y" - vertical position of the scan line. This parameter is
709 required.
710 • "x" - position to start on the scan line. Default: 0
712 • "pixels" - either a reference to an array containing
714 Imager::Color objects, an reference to an array containing
715 Imager::Color::Float objects or a scalar containing packed
716 color data.
717 If "type" is "index" then this can either be a reference to an
719 array of palette color indexes or a scalar containing packed
720 indexes.
721 See "Packed Color Data" for information on the format of packed
723 color data.
724 • "type" - the type of pixel data supplied. If you supply an
726 array reference then this is determined automatically. If you
727 supply packed color data this defaults to '8bit', if your data
728 is packed floating point color data then you need to set this
729 to 'float'.
730 You can use "float" or "8bit" samples with any image.
732 If this is "index" then "pixels" should be either an array of
734 palette color indexes or a packed string of color indexes.
735 Returns the number of pixels set.
737 Each of the following sets 5 pixels from (5, 10) through (9, 10) to
739 blue, red, blue, red, blue:
740 my $red_color = Imager::Color->new(255, 0, 0);
742 my $blue_color = Imager::Color->new(0, 0, 255);
743 $image->setscanline(y=>10, x=>5, pixels=>
745 [ ($blue_color, $red_color) x 2, $blue_color ]);
746 # use floating point color instead, for 16-bit plus images
748 my $red_colorf = Imager::Color::Float->new(1.0, 0, 0);
749 my $blue_colorf = Imager::Color::Float->new(0, 0, 1.0);
750 $image->setscanline(y=>10, x=>5, pixels=>
752 [ ($blue_colorf, $red_colorf) x 2, $blue_colorf ]);
753 # packed 8-bit data
755 $image->setscanline(y=>10, x=>5, pixels=>
756 pack("C*", ((0, 0, 255, 255), (255, 0, 0, 255)) x 2,
757 (0, 0, 255, 255)));
758 # packed floating point samples
760 $image->setscanline(y=>10, x=>5, type=>'float', pixels=>
761 pack("d*", ((0, 0, 1.0, 1.0), (1.0, 0, 0, 1.0)) x 2,
762 (0, 0, 1.0, 1.0)));
763 Copy even rows from one image to another:
765 for (my $y = 0; $y < $im2->getheight; $y+=2) {
767 $im1->setscanline(y=>$y,
768 pixels=>scalar($im2->getscanline(y=>$y)));
769 }
770 Set the blue channel to 0 for all pixels in an image. This could
772 be done with convert too:
773 for my $y (0..$im->getheight-1) {
775 my $row = $im->getscanline(y=>$y);
776 $row =~ s/(..).(.)/$1\0$2/gs;
777 $im->setscanline(y=>$y, pixels=>$row);
778 }
779 getscanline()
781 Read all or part of a horizontal line of pixels from an image.
782 This method is most useful in conjunction with "setscanline()".
783 The parameters you can pass are:
785 • "y" - vertical position of the scan line. This parameter is
787 required.
788 • "x" - position to start on the scan line. Default: 0
790 • "width" - number of pixels to read. Default: $img->getwidth -
792 x
793 • "type" - the type of pixel data to return. Default: "8bit".
795 Permitted values are "8bit" and "float" and "index".
797 In list context this method will return a list of Imager::Color
799 objects when type is "8bit", or a list of Imager::Color::Float
800 objects when type if "float", or a list of integers when type is
801 "index".
802 In scalar context this returns a packed 8-bit pixels when type is
804 "8bit", or a list of packed floating point pixels when type is
805 "float", or packed palette color indexes when type is "index".
806 The values of samples for which the image does not have channels is
808 undefined. For example, for a single channel image the values of
809 channels 1 through 3 are undefined.
810 Check image for a given color:
812 my $found;
814 YLOOP: for my $y (0..$img->getheight-1) {
815 my @colors = $img->getscanline(y=>$y);
816 for my $color (@colors) {
817 my ($red, $green, $blue, $alpha) = $color->rgba;
818 if ($red == $test_red && $green == $test_green && $blue == $test_blue
819 && $alpha == $test_alpha) {
820 ++$found;
821 last YLOOP;
822 }
823 }
824 }
825 Or do it using packed data:
827 my $found;
829 my $test_packed = pack("CCCC", $test_red, $test_green, $test_blue,
830 $test_alpha);
831 YLOOP: for my $y (0..$img->getheight-1) {
832 my $colors = $img->getscanline(y=>$y);
833 while (length $colors) {
834 if (substr($colors, 0, 4, '') eq $test_packed) {
835 ++$found;
836 last YLOOP;
837 }
838 }
839 }
840 Some of the examples for "setscanline()" for more examples.
842 getsamples()
844 Read specified channels from all or part of a horizontal line of
845 pixels from an image.
846 The parameters you can pass are:
848 • "y" - vertical position of the scan line. This parameter is
850 required.
851 • "x" - position to start on the scan line. Default: 0
853 • "width" - number of pixels to read. Default: "$img->getwidth -
855 x"
856 • "type" - the type of sample data to return. Default: "8bit".
858 Permitted values are "8bit" and "float".
860 As of Imager 0.61 this can be "16bit" only for 16 bit images.
862 • "channels" - a reference to an array of channels to return,
864 where 0 is the first channel. Default: "[ 0 ..
865 $self->getchannels()-1 ]"
866 • "target" - if an array reference is supplied in target then the
868 samples will be stored here instead of being returned.
869 • "offset" - the offset within the array referenced by target
871 In list context this will return a list of integers between 0 and
873 255 inclusive when type is "8bit", or a list of floating point
874 numbers between 0.0 and 1.0 inclusive when type is "float".
875 In scalar context this will return a string of packed bytes, as
877 with " pack("C*", ...) " when type is "8bit" or a string of packed
878 doubles as with " pack("d*", ...) " when type is "float".
879 If the target option is supplied then only a count of samples is
881 returned.
882 Example: Check if any pixels in an image have a non-zero alpha
884 channel:
885 my $has_coverage;
887 for my $y (0 .. $img->getheight()-1) {
888 my $alpha = $img->getsamples(y=>$y, channels=>[0]);
889 if ($alpha =~ /[^\0]/) {
890 ++$has_coverage;
891 last;
892 }
893 }
894 Example: Convert a 2 channel gray image into a 4 channel RGBA
896 image:
897 # this could be done with convert() instead
899 my $out = Imager->new(xsize => $src->getwidth(),
900 ysize => $src->getheight(),
901 channels => 4);
902 for my $y ( 0 .. $src->getheight()-1 ) {
903 my $data = $src->getsamples(y=>$y, channels=>[ 0, 0, 0, 1 ]);
904 $out->setscanline(y=>$y, pixels=>$data);
905 }
906 Retrieve 16-bit samples:
908 if ($img->bits == 16) {
910 my @samples;
911 $img->getsamples(x => 0, y => $y, target => \@samples, type => '16bit');
912 }
913 setsamples()
915 This allows writing of samples to an image.
916 Parameters:
918 • "y" - vertical position of the scan line. This parameter is
920 required.
921 • "x" - position to start on the scan line. Default: 0
923 • "width" - number of pixels to write. Default: "$img->getwidth
925 - x". The minimum of this and the number of pixels represented
926 by the samples provided will be written.
927 • "type" - the type of sample data to write. This parameter is
929 required.
930 This can be "8bit", "float" or for 16-bit images only, "16bit".
932 • "channels" - a reference to an array of channels to return,
934 where 0 is the first channel. Default: "[ 0 ..
935 $self->getchannels()-1 ]"
936 • "data" - for a type of "8bit" or "float" this can be a
938 reference to an array of samples or a scalar containing packed
939 samples. If "data" is a scalar it may only contain characters
940 from \x00 to \xFF.
941 For a type of "16bit" this can only be a reference to an array
943 of samples to write.
944 Required.
946 • "offset" - the starting offset within the array referenced by
948 data. If "data" is a scalar containing packed samples this
949 offset is in samples.
950 Returns the number of samples written.
952 $targ->setsamples(y => $y, data => \@data);
954 $targ->setsamples(y => $y, data => \@data, offset => $src->getchannels);
956 Copy from one image to another:
958 my $targ = Imager->new(xsize => $src->getwidth,
960 ysize => $src->getheight, channels => $src->getchannels);
961 for my $y (0 .. $targ->getheight()-1) {
962 my $row = $src->getsamples(y => $y)
963 or die $src->errstr;
964 $targ->setsamples(y => $y, data => $row)
965 or die $targ->errstr;;
966 }
967 Compose an image from separate source channels:
969 my @src = ...; # images to work from, up to 4
971 my $targ = Imager->new(xsize => $src[0]->getwidth,
972 ysize => $src[0]->getheight, channels => scalar(@src));
973 for my $y (0 .. $targ->getheight()-1) {
974 for my $ch (0 .. $#src) {
975 my $row = $src[$ch]->getsamples(y => $y, channels => [ 0 ]);
976 $targ->setsamples(y => $y, data => $row, channels => [ $ch ] );
977 }
978 }
979
981 The getscanline() and setscanline() methods can work with pixels packed
982 into scalars. This is useful to remove the cost of creating color
983 objects, but should only be used when performance is an issue.
984 The getsamples() and setsamples() methods can work with samples packed
986 into scalars.
987 Packed data can either be 1 byte per sample or 1 double per sample.
989 Each pixel returned by getscanline() or supplied to setscanline()
991 contains 4 samples, even if the image has fewer then 4 channels. The
992 values of the extra samples as returned by getscanline() is not
993 specified. The extra samples passed to setscanline() are ignored.
994 To produce packed 1 byte/sample pixels, use the pack "C" template:
996 my $packed_8bit_pixel = pack("CCCC", $red, $blue, $green, $alpha);
998 To produce packed double/sample pixels, use the pack "d" template:
1000 my $packed_float_pixel = pack("dddd", $red, $blue, $green, $alpha);
1002 Note that double/sample data is always stored using the C "double"
1004 type, never "long double", even if "perl" is built with
1005 "-Duselongdouble".
1006 If you use a type parameter of "index" then the values are palette
1008 color indexes, not sample values:
1009 my $im = Imager->new(xsize => 100, ysize => 100, type => 'paletted');
1011 my $black_index = $im->addcolors(colors => [ 'black' ]);
1012 my $red_index = $im->addcolors(colors => [ 'red' ]);
1013 # 2 pixels
1014 my $packed_index_data = pack("C*", $black_index, $red_index);
1015 $im->setscanline(y => $y, pixels => $packed_index_data, type => 'index');
1016
1018 Some methods accept a "combine" parameter, this can be any of the
1019 following:
1020 "none"
1022 The fill pixel replaces the target pixel.
1023 "normal"
1025 The fill pixels alpha value is used to combine it with the target
1026 pixel.
1027 "multiply"
1029 "mult"
1030 Each channel of fill and target is multiplied, and the result is
1031 combined using the alpha channel of the fill pixel.
1032 "dissolve"
1034 If the alpha of the fill pixel is greater than a random number, the
1035 fill pixel is alpha combined with the target pixel.
1036 "add"
1038 The channels of the fill and target are added together, clamped to
1039 the range of the samples and alpha combined with the target.
1040 "subtract"
1042 The channels of the fill are subtracted from the target, clamped to
1043 be >= 0, and alpha combined with the target.
1044 "diff"
1046 The channels of the fill are subtracted from the target and the
1047 absolute value taken this is alpha combined with the target.
1048 "lighten"
1050 The higher value is taken from each channel of the fill and target
1051 pixels, which is then alpha combined with the target.
1052 "darken"
1054 The higher value is taken from each channel of the fill and target
1055 pixels, which is then alpha combined with the target.
1056 "hue"
1058 The combination of the saturation and value of the target is
1059 combined with the hue of the fill pixel, and is then alpha combined
1060 with the target.
1061 "sat"
1063 The combination of the hue and value of the target is combined with
1064 the saturation of the fill pixel, and is then alpha combined with
1065 the target.
1066 "value"
1068 The combination of the hue and value of the target is combined with
1069 the value of the fill pixel, and is then alpha combined with the
1070 target.
1071 "color"
1073 The combination of the value of the target is combined with the hue
1074 and saturation of the fill pixel, and is then alpha combined with
1075 the target.
1076 combines()
1078 Returns a list of possible combine types.
1079
1081 box() does not support anti-aliasing yet. Default color is not unified
1082 yet.
1083
1085 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson.
1086
1088 Imager(3), Imager::Cookbook(3)
1089
1091 $Revision$
1092perl v5.32.1 2021-01-27 Imager::Draw(3)