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() and the
109 flood_fill() method can take a "fill" parameter instead of a "color"
110 parameter which can either be an Imager::Fill object, or a reference to
111 a hash containing the parameters used to create the fill, for example:
112 $image->box(..., fill=>{ hatch => 'check1x1' });
114 my $fillimage = Imager->new;
115 $fillimage->read(file=>$somefile) or die;
116 $image->flood_fill(..., fill=>{ image=>$fillimage });
117 Currently you can create opaque or transparent plain color fills,
119 hatched fills, image based fills and fountain fills. See Imager::Fill
120 for more information.
121 Polygon Fill Modes
123 When filling a polygon that overlaps itself, or when filling several
124 polygons with polypolygon() that overlap each other, you can supply a
125 "mode" parameter that controls how the overlap is resolved. This can
126 have one of two possible values:
127 • "evenodd" - if areas overlap an odd number of times, they are
129 filled, and are otherwise unfilled. This is the default and the
130 historical Imager polygon fill mode.
131 • "nonzero" - areas that have an unbalanced clockwise and anti-
133 clockwise boundary are filled. This is the same as "WindingRule"
134 for X and "WINDING" for Win32 GDI.
135 "nonzero" allows polygons to overlap, either with itself, or with
137 another polygon in the same polypolygon() call, without producing
138 unfilled area in the overlap, and also allows areas to be cut out of
139 the area by specifying the points making up a cut-out in the opposite
140 order.
141 List of primitives
143 line()
144 $img->line(color=>$green, x1=>10, x2=>100,
145 y1=>20, y2=>50, aa=>1, endp=>1 );
146 Draws a line from (x1,y1) to (x2,y2). The endpoint (x2,y2) is
148 drawn by default. If "endp" of 0 is specified then the endpoint
149 will not be drawn. If "aa" is set then the line will be drawn
150 anti-aliased. The "antialias" parameter is still available for
151 backwards compatibility.
152 Parameters:
154 • "x1", "y1" - starting point of the line. Required.
156 • "x2", "y2" - end point of the line. Required.
158 • "color" - the color of the line. See "Color Parameters".
160 Default: black.
161 • "endp" - if zero the end point of the line is not drawn.
163 Default: 1 - the end point is drawn. This is useful to set to
164 0 when drawing a series of connected lines.
165 • "aa" - if true the line is drawn anti-aliased. Default: 0.
167 polyline()
169 $img->polyline(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
170 $img->polyline(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], aa=>1);
171 "polyline" is used to draw multiple lines between a series of
173 points. The point set can either be specified as an arrayref to an
174 array of array references (where each such array represents a
175 point). The other way is to specify two array references.
176 The "antialias" parameter is still available for backwards
178 compatibility.
179 • points - a reference to an array of references to arrays
181 containing the co-ordinates of the points in the line, for
182 example:
183 my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] );
185 $img->polyline(points => \@points);
186 • x, y - each is an array of x or y ordinates. This is an
188 alternative to supplying the "points" parameter.
189 # same as the above points example
191 my @x = ( 0, 100, 100, 0 );
192 my @y = ( 0, 0, 100, 100 );
193 $img->polyline(x => \@x, y => \@y);
194 • "color" - the color of the line. See "Color Parameters".
196 Default: black.
197 • "aa" - if true the line is drawn anti-aliased. Default: 0.
199 Can also be supplied as "antialias" for backward compatibility.
200 box()
202 $blue = Imager::Color->new( 0, 0, 255 );
203 $img->box(color => $blue, xmin=>10, ymin=>30, xmax=>200, ymax=>300,
204 filled=>1);
205 If any of the edges of the box are omitted it will snap to the
207 outer edge of the image in that direction. If "filled" is omitted
208 the box is drawn as an outline. Instead of a color it is possible
209 to use a "fill" pattern:
210 $fill = Imager::Fill->new(hatch=>'stipple');
212 $img->box(fill=>$fill); # fill entire image with a given fill pattern
213 $img->box(xmin=>10, ymin=>30, xmax=>150, ymax=>60,
215 fill => { hatch=>'cross2' });
216 Also if a color is omitted a color with (255,255,255,255) is used
218 instead. [NOTE: This may change to use "$img->fgcolor()" in the
219 future].
220 Box does not support fractional coordinates yet.
222 Parameters:
224 • "xmin" - left side of the box. Default: 0 (left edge of the
226 image)
227 • "ymin" - top side of the box. Default: 0 (top edge of the
229 image)
230 • "xmax" - right side of the box. Default: "$img->getwidth-1".
232 (right edge of the image)
233 • "ymax" - bottom side of the box. Default: "$img->getheight-1".
235 (bottom edge of the image)
236 Note: "xmax" and "ymax" are inclusive - the number of pixels
238 drawn for a filled box is "(xmax-xmin+1) * (ymax-ymin+1)".
239 • "box" - a reference to an array of (left, top, right, bottom)
241 co-ordinates. This is an alternative to supplying "xmin",
242 "ymin", "xmax", "ymax" and overrides their values.
243 • "color" - the color of the line. See "Color Parameters".
245 Default: white. This is ignored if the filled parameter
246 • "filled" - if non-zero the box is filled with color instead of
248 outlined. Default: an outline is drawn.
249 • "fill" - the fill for the box. If this is supplied then the
251 box will be filled. See "Fill Parameters".
252 arc()
254 $img->arc(color=>$red, r=>20, x=>200, y=>100, d1=>10, d2=>20 );
255 This creates a filled red arc with a 'center' at (200, 100) and
257 spans 10 degrees and the slice has a radius of 20.
258 It's also possible to supply a "fill" parameter.
260 To draw just an arc outline - just the curve, not the radius lines,
262 set filled to 0:
263 Parameters:
265 $img->arc(color=>$red, r=>20, x=>200, y=>100, d1=>10, d2=>20, filled=>0 );
267 • "x", "y" - center of the filled arc. Default: center of the
269 image.
270 • "r" - radius of the arc. Default: 1/3 of min(image height,
272 image width).
273 • "d1" - starting angle of the arc, in degrees. Default: 0
275 • "d2" - ending angle of the arc, in degrees. Default: 361.
277 • "color" - the color of the filled arc. See "Color Parameters".
279 Default: white. Overridden by "fill".
280 • "fill" - the fill for the filled arc. See "Fill Parameters"
282 • "aa" - if true the filled arc is drawn anti-aliased. Default:
284 false.
285 Anti-aliased arc() is experimental for now, I'm not entirely
287 happy with the results in some cases.
288 • "filled" - set to 0 to draw only an outline.
290 # arc going through angle zero:
292 $img->arc(d1=>320, d2=>40, x=>100, y=>100, r=>50, color=>'blue');
293 # complex fill arc
295 $img->arc(d1=>135, d2=>45, x=>100, y=>150, r=>50,
296 fill=>{ solid=>'red', combine=>'diff' });
297 # draw an anti-aliased circle outline
299 $img->arc(x => 100, y => 150, r => 150, filled => 0,
300 color => '#F00', aa => 1);
301 # draw an anti-aliased arc
303 $img->arc(x => 100, y => 150, r => 90, filled => 0,
304 color => '#0f0', aa => 1, d1 => 90, d2 => 180);
305 circle()
307 $img->circle(color=>$green, r=>50, x=>200, y=>100, aa=>1, filled=>1);
308 This creates an anti-aliased green circle with its center at (200,
310 100) and has a radius of 50. It's also possible to supply a "fill"
311 parameter instead of a color parameter.
312 $img->circle(r => 50, x=> 150, y => 150, fill=>{ hatch => 'stipple' });
314 To draw a circular outline, set "filled" to 0:
316 $img->circle(color=>$green, r=>50, x=>200, y=>100, aa=>1, filled=>0);
318 • "x", "y" - center of the filled circle. Default: center of the
320 image.
321 • "r" - radius of the circle. Default: 1/3 of min(image height,
323 image width).
324 • "color" - the color of the filled circle. See "Color
326 Parameters". Default: white. Overridden by "fill".
327 • "fill" - the fill for the filled circle. See "Fill Parameters"
329 • "aa" - if true the filled circle is drawn anti-aliased.
331 Default: false.
332 • "filled" - set to 0 to just draw an outline.
334 polygon()
336 $img->polygon(points=>[[$x0,$y0],[$x1,$y1],[$x2,$y2]],color=>$red);
337 $img->polygon(x=>[$x0,$x1,$x2], y=>[$y0,$y1,$y2], fill=>$fill);
338 Polygon is used to draw a filled polygon. Currently the polygon is
340 always drawn anti-aliased, although that will change in the future.
341 Like other anti-aliased drawing functions its coordinates can be
342 specified with floating point values. As with other filled shapes
343 it's possible to use a "fill" instead of a color.
344 • "points" - a reference to an array of references to arrays
346 containing the co-ordinates of the points in the line, for
347 example:
348 my @points = ( [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ] );
350 $img->polygon(points => \@points);
351 • "x", "y" - each is an array of x or y ordinates. This is an
353 alternative to supplying the "points" parameter.
354 # same as the above points example
356 my @x = ( 0, 100, 100, 0 );
357 my @y = ( 0, 0, 100, 100 );
358 $img->polygon(x => \@x, y => \@y);
359 • "color" - the color of the filled polygon. See "Color
361 Parameters". Default: black. Overridden by "fill".
362 • "fill" - the fill for the filled circle. See "Fill Parameters"
364 • "mode" - fill mode for the polygon. See "Polygon Fill Modes"
366 Note: the points specified are as offsets from the top-left of the
368 image, not as pixel locations. This means that:
369 $img->polygon(points => [ [ 0, 0 ], [ 1, 0 ], [ 1, 1 ], [ 0, 1 ] ]);
371 fills only a single pixel at "(0, 0)", not four.
373 polypolygon()
375 $img->polypolygon(points => $points, color => $color);
376 Draw multiple polygons, either filled or unfilled.
378 • "points" - is an array reference containing polygon
380 definitions, each polygon definition is a reference to an array
381 containing two arrays, one each for the "x" and "y" co-
382 ordinates.
383 • "filled" - if true, fill the polygons with the color defined by
385 "color".
386 • "color" - the color to draw the polygons with if "fill" is not
388 supplied.
389 • "fill" - fill the polygons with this fill if supplied.
391 • "mode" - fill mode for the polygon. See "Polygon Fill Modes"
393 Note: the points specified are as offsets from the top-left of the
395 image, not as pixel locations. This means that:
396 $img->polypolygon(points => [ [ [ 0, 1, 1, 0 ], [ 0, 0, 1, 1 ] ] ],
398 filled => 1);
399 fills only a single pixel at "(0, 0)", not four.
401 flood_fill()
403 You can fill a region that all has the same color using the
404 flood_fill() method, for example:
405 $img->flood_fill(x=>50, y=>50, color=>$color);
407 will fill all regions the same color connected to the point (50,
409 50).
410 Alternatively you can fill a region limited by a given border
412 color:
413 # stop at the red border
415 $im->flood_fill(x=>50, y=>50, color=>$color, border=>"red");
416 You can also fill with a complex fill:
418 $img->flood_fill(x=>50, y=>50, fill=>{ hatch=>'cross1x1' });
420 Parameters:
422 • "x", "y" - the start point of the fill.
424 • "color" - the color of the filled area. See "Color
426 Parameters". Default: white. Overridden by "fill".
427 • "fill" - the fill for the filled area. See "Fill Parameters"
429 • "border" - the border color of the region to be filled. If
431 this parameter is supplied flood_fill() will stop when it finds
432 this color. If this is not supplied then a normal fill is
433 done. "border" can be supplied as a "Color Parameters".
434 setpixel()
436 $img->setpixel(x=>50, y=>70, color=>$color);
437 $img->setpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40], color=>$color);
438 setpixel() is used to set one or more individual pixels.
440 You can supply a single set of co-ordinates as scalar "x" and "y"
442 parameters, or set either to an arrayref of ordinates.
443 If one array is shorter than another the final value in the shorter
445 will be duplicated until they match in length.
446 If only one of "x" or "y" is an array reference then setpixel()
448 will behave as if the non-reference value were an array reference
449 containing only that value.
450 eg.
452 my $count = $img->setpixel(x => 1, y => [ 0 .. 3 ], color => $color);
454 behaves like:
456 my $count = $img->setpixel(x => [ 1 ], y => [ 0 .. 3 ], color => $color);
458 and since the final element in the shorter array is duplicated,
460 this behaves like:
461 my $count = $img->setpixel(x => [ 1, 1, 1, 1 ], y => [ 0 .. 3 ],
463 color => $color);
464 To set an entire or partial row of pixels in one call, consider the
466 "setscanline()" in Imager::Draw or "setsamples()" in Imager::Draw
467 methods.
468 Parameters:
470 • x, y - either integers giving the co-ordinates of the pixel to
472 set or array references containing a set of pixels to be set.
473 • color - the color of the pixels drawn. See "Color Parameters".
475 Default: white.
476 Returns the number of pixels drawn, if no pixels were drawn, but
478 none of the errors below occur, returns "0 but true".
479 For other errors, setpixel() returns an empty list and sets
481 errstr().
482 Possible errors conditions include:
484 • the image supplied is empty
486 • a reference to an empty array was supplied for "x" or "y"
488 • "x" or "y" wasn't supplied
490 • "color" isn't a valid color, and can't be converted to a color.
492 getpixel()
494 my $color = $img->getpixel(x=>50, y=>70); my @colors =
495 $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]); my $colors_ref =
496 $img->getpixel(x=>[ 50, 60, 70 ], y=>[20, 30, 40]);
497 getpixel() is used to retrieve one or more individual pixels.
499 You can supply a single set of co-ordinates as scalar "x" and "y"
501 parameters, or set each to an arrayref of ordinates.
502 If one array is shorter than another the final value in the shorter
504 will be duplicated until they match in length.
505 If only one of "x" or "y" is an array reference then getpixel()
507 will behave as if the non-reference value were an array reference
508 containing only that value.
509 eg.
511 my @colors = $img->getpixel(x => 0, y => [ 0 .. 3 ]);
513 behaves like:
515 my @colors = $img->getpixel(x => [ 0 ], y => [ 0 .. 3 ]);
517 and since the final element in the shorter array is duplicated,
519 this behaves like:
520 my @colors = $img->getpixel(x => [ 0, 0, 0, 0 ], y => [ 0 .. 3 ]);
522 To receive floating point colors from getpixel(), set the "type"
524 parameter to 'float'.
525 To retrieve an entire or partial row of pixels, or pixel data, in
527 one call, consider the "getscanline()" in Imager::Draw or
528 "getsamples()" in Imager::Draw methods.
529 Parameters:
531 • "x", "y" - either integers giving the co-ordinates of the pixel
533 to set or array references containing a set of pixels to be
534 set.
535 • "type" - the type of color object to return, either '8bit' for
537 Imager::Color objects or 'float' for Imager::Color::Float
538 objects. Default: '8bit'.
539 When called with an array reference for either or "x" or "y",
541 getpixel() will return a list of colors in list context, and an
542 arrayref in scalar context.
543 If a supplied co-ordinate is outside the image then "undef" is
545 returned for the pixel.
546 Each color is returned as an Imager::Color object or as an
548 Imager::Color::Float object if "type" is set to "float".
549 Possible errors conditions include:
551 • the image supplied is empty
553 • a reference to an empty array was supplied for "x" or "y"
555 • "x" or "y" wasn't supplied
557 • "type" isn't a valid value.
559 For any of these errors getpixel() returns an empty list.
561 string()
563 my $font = Imager::Font->new(file=>"foo.ttf");
564 $img->string(x => 50, y => 70,
565 string => "Hello, World!",
566 font => $font,
567 size => 30,
568 aa => 1,
569 color => 'white');
570 Draws text on the image.
572 Parameters:
574 • "x", "y" - the point to draw the text from. If "align" is 0
576 this is the top left of the string. If "align" is 1 (the
577 default) then this is the left of the string on the baseline.
578 Required.
579 • "string" - the text to draw. Required unless you supply the
581 "text" parameter.
582 • "font" - an Imager::Font object representing the font to draw
584 the text with. Required.
585 • "aa" - if non-zero the output will be anti-aliased. Default:
587 the value set in Imager::Font->new() or 0 if not set.
588 • "align" - if non-zero the point supplied in (x,y) will be on
590 the base-line, if zero then (x,y) will be at the top-left of
591 the string.
592 i.e. if drawing the string "yA" and align is 0 the point (x,y)
594 will aligned with the top of the A. If align is 1 (the
595 default) it will be aligned with the baseline of the font,
596 typically bottom of the A, depending on the font used.
597 Default: the value set in Imager::Font->new, or 1 if not set.
599 • "channel" - if present, the text will be written to the
601 specified channel of the image and the color parameter will be
602 ignore.
603 • "color" - the color to draw the text in. Default: the color
605 supplied to Imager::Font->new, or red if none.
606 • "size" - the point size to draw the text at. Default: the size
608 supplied to Imager::Font->new, or 15.
609 • "sizew" - the width scaling to draw the text at. Default: the
611 value of "size".
612 • "utf8" - for drivers that support it, treat the string as UTF-8
614 encoded. For versions of perl that support Unicode (5.6 and
615 later), this will be enabled automatically if the "string"
616 parameter is already a UTF-8 string. See "UTF-8" in
617 Imager::Font for more information.
618 • "vlayout" - for drivers that support it, draw the text
620 vertically. Note: I haven't found a font that has the
621 appropriate metrics yet.
622 • "text" - alias for the "string" parameter.
624 On error, string() returns false and you can use $img->errstr to
626 get the reason for the error.
627 align_string()
629 Draws text aligned around a point on the image.
630 # "Hello" centered at 100, 100 in the image.
632 my ($left, $top, $right, $bottom) =
633 $img->align_string(string=>"Hello",
634 x=>100, y=>100,
635 halign=>'center', valign=>'center',
636 font=>$font);
637 Parameters:
639 • "x", "y" - the point to draw the text from. If "align" is 0
641 this is the top left of the string. If "align" is 1 (the
642 default) then this is the left of the string on the baseline.
643 Required.
644 • "string" - the text to draw. Required unless you supply the
646 "text" parameter.
647 • "font" - an Imager::Font object representing the font to draw
649 the text with. Required.
650 • "aa" - if non-zero the output will be anti-aliased
652 • "valign" - vertical alignment of the text against (x,y)
654 • "top" - Point is at the top of the text.
656 • "bottom" - Point is at the bottom of the text.
658 • "baseline" - Point is on the baseline of the text. This is
660 the default.
661 • "center" - Point is vertically centered within the text.
663 • "halign" - horizontal alignment of the text against (x,y)
665 • "left" - The point is at the left of the text. This is the
667 default.
668 • "start" - The point is at the start point of the text.
670 • "center" - The point is horizontally centered within the
672 text.
673 • "right" - The point is at the right end of the text.
675 • "end" - The point is at the end point of the text.
677 • "channel" - if present, the text will be written to the
679 specified channel of the image and the color parameter will be
680 ignore.
681 • "color" - the color to draw the text in. Default: the color
683 supplied to Imager::Font->new, or red if none.
684 • "size" - the point size to draw the text at. Default: the size
686 supplied to Imager::Font->new, or 15.
687 • "sizew" - the width scaling to draw the text at. Default: the
689 value of "size".
690 • "utf8" - for drivers that support it, treat the string as UTF-8
692 encoded. For versions of perl that support Unicode (5.6 and
693 later), this will be enabled automatically if the "string"
694 parameter is already a UTF-8 string. See "UTF-8" in
695 Imager::Font for more information.
696 • "vlayout" - for drivers that support it, draw the text
698 vertically. Note: I haven't found a font that has the
699 appropriate metrics yet.
700 • "text" - alias for the "string" parameter.
702 On success returns a list of bounds of the drawn text, in the order
704 left, top, right, bottom.
705 On error, align_string() returns an empty list and you can use
707 "$img->errstr" to get the reason for the error.
708 setscanline()
710 Set all or part of a horizontal line of pixels to an image. This
711 method is most useful in conjunction with "getscanline()".
712 The parameters you can pass are:
714 • "y" - vertical position of the scan line. This parameter is
716 required.
717 • "x" - position to start on the scan line. Default: 0
719 • "pixels" - either a reference to an array containing
721 Imager::Color objects, an reference to an array containing
722 Imager::Color::Float objects or a scalar containing packed
723 color data.
724 If "type" is "index" then this can either be a reference to an
726 array of palette color indexes or a scalar containing packed
727 indexes.
728 See "Packed Color Data" for information on the format of packed
730 color data.
731 • "type" - the type of pixel data supplied. If you supply an
733 array reference then this is determined automatically. If you
734 supply packed color data this defaults to '8bit', if your data
735 is packed floating point color data then you need to set this
736 to 'float'.
737 You can use "float" or "8bit" samples with any image.
739 If this is "index" then "pixels" should be either an array of
741 palette color indexes or a packed string of color indexes.
742 Returns the number of pixels set.
744 Each of the following sets 5 pixels from (5, 10) through (9, 10) to
746 blue, red, blue, red, blue:
747 my $red_color = Imager::Color->new(255, 0, 0);
749 my $blue_color = Imager::Color->new(0, 0, 255);
750 $image->setscanline(y=>10, x=>5, pixels=>
752 [ ($blue_color, $red_color) x 2, $blue_color ]);
753 # use floating point color instead, for 16-bit plus images
755 my $red_colorf = Imager::Color::Float->new(1.0, 0, 0);
756 my $blue_colorf = Imager::Color::Float->new(0, 0, 1.0);
757 $image->setscanline(y=>10, x=>5, pixels=>
759 [ ($blue_colorf, $red_colorf) x 2, $blue_colorf ]);
760 # packed 8-bit data
762 $image->setscanline(y=>10, x=>5, pixels=>
763 pack("C*", ((0, 0, 255, 255), (255, 0, 0, 255)) x 2,
764 (0, 0, 255, 255)));
765 # packed floating point samples
767 $image->setscanline(y=>10, x=>5, type=>'float', pixels=>
768 pack("d*", ((0, 0, 1.0, 1.0), (1.0, 0, 0, 1.0)) x 2,
769 (0, 0, 1.0, 1.0)));
770 Copy even rows from one image to another:
772 for (my $y = 0; $y < $im2->getheight; $y+=2) {
774 $im1->setscanline(y=>$y,
775 pixels=>scalar($im2->getscanline(y=>$y)));
776 }
777 Set the blue channel to 0 for all pixels in an image. This could
779 be done with convert too:
780 for my $y (0..$im->getheight-1) {
782 my $row = $im->getscanline(y=>$y);
783 $row =~ s/(..).(.)/$1\0$2/gs;
784 $im->setscanline(y=>$y, pixels=>$row);
785 }
786 getscanline()
788 Read all or part of a horizontal line of pixels from an image.
789 This method is most useful in conjunction with "setscanline()".
790 The parameters you can pass are:
792 • "y" - vertical position of the scan line. This parameter is
794 required.
795 • "x" - position to start on the scan line. Default: 0
797 • "width" - number of pixels to read. Default: $img->getwidth -
799 x
800 • "type" - the type of pixel data to return. Default: "8bit".
802 Permitted values are "8bit" and "float" and "index".
804 In list context this method will return a list of Imager::Color
806 objects when type is "8bit", or a list of Imager::Color::Float
807 objects when type if "float", or a list of integers when type is
808 "index".
809 In scalar context this returns a packed 8-bit pixels when type is
811 "8bit", or a list of packed floating point pixels when type is
812 "float", or packed palette color indexes when type is "index".
813 The values of samples for which the image does not have channels is
815 undefined. For example, for a single channel image the values of
816 channels 1 through 3 are undefined.
817 Check image for a given color:
819 my $found;
821 YLOOP: for my $y (0..$img->getheight-1) {
822 my @colors = $img->getscanline(y=>$y);
823 for my $color (@colors) {
824 my ($red, $green, $blue, $alpha) = $color->rgba;
825 if ($red == $test_red && $green == $test_green && $blue == $test_blue
826 && $alpha == $test_alpha) {
827 ++$found;
828 last YLOOP;
829 }
830 }
831 }
832 Or do it using packed data:
834 my $found;
836 my $test_packed = pack("CCCC", $test_red, $test_green, $test_blue,
837 $test_alpha);
838 YLOOP: for my $y (0..$img->getheight-1) {
839 my $colors = $img->getscanline(y=>$y);
840 while (length $colors) {
841 if (substr($colors, 0, 4, '') eq $test_packed) {
842 ++$found;
843 last YLOOP;
844 }
845 }
846 }
847 Some of the examples for "setscanline()" for more examples.
849 getsamples()
851 Read specified channels from all or part of a horizontal line of
852 pixels from an image.
853 The parameters you can pass are:
855 • "y" - vertical position of the scan line. This parameter is
857 required.
858 • "x" - position to start on the scan line. Default: 0
860 • "width" - number of pixels to read. Default: "$img->getwidth -
862 x"
863 • "type" - the type of sample data to return. Default: "8bit".
865 Permitted values are "8bit" and "float".
867 As of Imager 0.61 this can be "16bit" only for 16 bit images.
869 • "channels" - a reference to an array of channels to return,
871 where 0 is the first channel. Default: "[ 0 ..
872 $self->getchannels()-1 ]"
873 • "target" - if an array reference is supplied in target then the
875 samples will be stored here instead of being returned.
876 • "offset" - the offset within the array referenced by target
878 In list context this will return a list of integers between 0 and
880 255 inclusive when type is "8bit", or a list of floating point
881 numbers between 0.0 and 1.0 inclusive when type is "float".
882 In scalar context this will return a string of packed bytes, as
884 with " pack("C*", ...) " when type is "8bit" or a string of packed
885 doubles as with " pack("d*", ...) " when type is "float".
886 If the target option is supplied then only a count of samples is
888 returned.
889 Example: Check if any pixels in an image have a non-zero alpha
891 channel:
892 my $has_coverage;
894 for my $y (0 .. $img->getheight()-1) {
895 my $alpha = $img->getsamples(y=>$y, channels=>[0]);
896 if ($alpha =~ /[^\0]/) {
897 ++$has_coverage;
898 last;
899 }
900 }
901 Example: Convert a 2 channel gray image into a 4 channel RGBA
903 image:
904 # this could be done with convert() instead
906 my $out = Imager->new(xsize => $src->getwidth(),
907 ysize => $src->getheight(),
908 channels => 4);
909 for my $y ( 0 .. $src->getheight()-1 ) {
910 my $data = $src->getsamples(y=>$y, channels=>[ 0, 0, 0, 1 ]);
911 $out->setscanline(y=>$y, pixels=>$data);
912 }
913 Retrieve 16-bit samples:
915 if ($img->bits == 16) {
917 my @samples;
918 $img->getsamples(x => 0, y => $y, target => \@samples, type => '16bit');
919 }
920 setsamples()
922 This allows writing of samples to an image.
923 Parameters:
925 • "y" - vertical position of the scan line. This parameter is
927 required.
928 • "x" - position to start on the scan line. Default: 0
930 • "width" - number of pixels to write. Default: "$img->getwidth
932 - x". The minimum of this and the number of pixels represented
933 by the samples provided will be written.
934 • "type" - the type of sample data to write. This parameter is
936 required.
937 This can be "8bit", "float" or for 16-bit images only, "16bit".
939 • "channels" - a reference to an array of channels to return,
941 where 0 is the first channel. Default: "[ 0 ..
942 $self->getchannels()-1 ]"
943 • "data" - for a type of "8bit" or "float" this can be a
945 reference to an array of samples or a scalar containing packed
946 samples. If "data" is a scalar it may only contain characters
947 from \x00 to \xFF.
948 For a type of "16bit" this can only be a reference to an array
950 of samples to write.
951 Required.
953 • "offset" - the starting offset within the array referenced by
955 data. If "data" is a scalar containing packed samples this
956 offset is in samples.
957 Returns the number of samples written.
959 $targ->setsamples(y => $y, data => \@data);
961 $targ->setsamples(y => $y, data => \@data, offset => $src->getchannels);
963 Copy from one image to another:
965 my $targ = Imager->new(xsize => $src->getwidth,
967 ysize => $src->getheight, channels => $src->getchannels);
968 for my $y (0 .. $targ->getheight()-1) {
969 my $row = $src->getsamples(y => $y)
970 or die $src->errstr;
971 $targ->setsamples(y => $y, data => $row)
972 or die $targ->errstr;;
973 }
974 Compose an image from separate source channels:
976 my @src = ...; # images to work from, up to 4
978 my $targ = Imager->new(xsize => $src[0]->getwidth,
979 ysize => $src[0]->getheight, channels => scalar(@src));
980 for my $y (0 .. $targ->getheight()-1) {
981 for my $ch (0 .. $#src) {
982 my $row = $src[$ch]->getsamples(y => $y, channels => [ 0 ]);
983 $targ->setsamples(y => $y, data => $row, channels => [ $ch ] );
984 }
985 }
986
988 The getscanline() and setscanline() methods can work with pixels packed
989 into scalars. This is useful to remove the cost of creating color
990 objects, but should only be used when performance is an issue.
991 The getsamples() and setsamples() methods can work with samples packed
993 into scalars.
994 Packed data can either be 1 byte per sample or 1 double per sample.
996 Each pixel returned by getscanline() or supplied to setscanline()
998 contains 4 samples, even if the image has fewer then 4 channels. The
999 values of the extra samples as returned by getscanline() is not
1000 specified. The extra samples passed to setscanline() are ignored.
1001 To produce packed 1 byte/sample pixels, use the pack "C" template:
1003 my $packed_8bit_pixel = pack("CCCC", $red, $blue, $green, $alpha);
1005 To produce packed double/sample pixels, use the pack "d" template:
1007 my $packed_float_pixel = pack("dddd", $red, $blue, $green, $alpha);
1009 Note that double/sample data is always stored using the C "double"
1011 type, never "long double", even if "perl" is built with
1012 "-Duselongdouble".
1013 If you use a type parameter of "index" then the values are palette
1015 color indexes, not sample values:
1016 my $im = Imager->new(xsize => 100, ysize => 100, type => 'paletted');
1018 my $black_index = $im->addcolors(colors => [ 'black' ]);
1019 my $red_index = $im->addcolors(colors => [ 'red' ]);
1020 # 2 pixels
1021 my $packed_index_data = pack("C*", $black_index, $red_index);
1022 $im->setscanline(y => $y, pixels => $packed_index_data, type => 'index');
1023
1025 Some methods accept a "combine" parameter, this can be any of the
1026 following:
1027 "none"
1029 The fill pixel replaces the target pixel.
1030 "normal"
1032 The fill pixels alpha value is used to combine it with the target
1033 pixel.
1034 "multiply"
1036 "mult"
1037 Each channel of fill and target is multiplied, and the result is
1038 combined using the alpha channel of the fill pixel.
1039 "dissolve"
1041 If the alpha of the fill pixel is greater than a random number, the
1042 fill pixel is alpha combined with the target pixel.
1043 "add"
1045 The channels of the fill and target are added together, clamped to
1046 the range of the samples and alpha combined with the target.
1047 "subtract"
1049 The channels of the fill are subtracted from the target, clamped to
1050 be >= 0, and alpha combined with the target.
1051 "diff"
1053 The channels of the fill are subtracted from the target and the
1054 absolute value taken this is alpha combined with the target.
1055 "lighten"
1057 The higher value is taken from each channel of the fill and target
1058 pixels, which is then alpha combined with the target.
1059 "darken"
1061 The higher value is taken from each channel of the fill and target
1062 pixels, which is then alpha combined with the target.
1063 "hue"
1065 The combination of the saturation and value of the target is
1066 combined with the hue of the fill pixel, and is then alpha combined
1067 with the target.
1068 "sat"
1070 The combination of the hue and value of the target is combined with
1071 the saturation of the fill pixel, and is then alpha combined with
1072 the target.
1073 "value"
1075 The combination of the hue and value of the target is combined with
1076 the value of the fill pixel, and is then alpha combined with the
1077 target.
1078 "color"
1080 The combination of the value of the target is combined with the hue
1081 and saturation of the fill pixel, and is then alpha combined with
1082 the target.
1083 combines()
1085 Returns a list of possible combine types.
1086
1088 box() does not support anti-aliasing yet. Default color is not unified
1089 yet.
1090
1092 Tony Cook <tonyc@cpan.org>, Arnar M. Hrafnkelsson.
1093
1095 Imager(3), Imager::Cookbook(3)
1096
1098 $Revision$
1099perl v5.38.0 2023-07-20 Imager::Draw(3)