1Imager(3) User Contributed Perl Documentation Imager(3)
2
3
4
6 Imager - Perl extension for Generating 24 bit Images
7
9 # Thumbnail example
10
11 #!/usr/bin/perl -w
12 use strict;
13 use Imager;
14
15 die "Usage: thumbmake.pl filename\n" if !-f $ARGV[0];
16 my $file = shift;
17
18 my $format;
19
20 # see Imager::Files for information on the read() method
21 my $img = Imager->new(file=>$file)
22 or die Imager->errstr();
23
24 $file =~ s/\.[^.]*$//;
25
26 # Create smaller version
27 # documented in Imager::Transformations
28 my $thumb = $img->scale(scalefactor=>.3);
29
30 # Autostretch individual channels
31 $thumb->filter(type=>'autolevels');
32
33 # try to save in one of these formats
34 SAVE:
35
36 for $format ( qw( png gif jpeg tiff ppm ) ) {
37 # Check if given format is supported
38 if ($Imager::formats{$format}) {
39 $file.="_low.$format";
40 print "Storing image as: $file\n";
41 # documented in Imager::Files
42 $thumb->write(file=>$file) or
43 die $thumb->errstr;
44 last SAVE;
45 }
46 }
47
49 Imager is a module for creating and altering images. It can read and
50 write various image formats, draw primitive shapes like lines,and
51 polygons, blend multiple images together in various ways, scale, crop,
52 render text and more.
53
54 Overview of documentation
55 · Imager - This document - Synopsis, Example, Table of Contents and
56 Overview.
57
58 · Imager::Install - installation notes for Imager.
59
60 · Imager::Tutorial - a brief introduction to Imager.
61
62 · Imager::Cookbook - how to do various things with Imager.
63
64 · Imager::ImageTypes - Basics of constructing image objects with
65 "new()": Direct type/virtual images, RGB(A)/paletted images,
66 8/16/double bits/channel, color maps, channel masks, image tags,
67 color quantization. Also discusses basic image information
68 methods.
69
70 · Imager::Files - IO interaction, reading/writing images, format
71 specific tags.
72
73 · Imager::Draw - Drawing Primitives, lines, boxes, circles, arcs,
74 flood fill.
75
76 · Imager::Color - Color specification.
77
78 · Imager::Fill - Fill pattern specification.
79
80 · Imager::Font - General font rendering, bounding boxes and font
81 metrics.
82
83 · Imager::Transformations - Copying, scaling, cropping, flipping,
84 blending, pasting, convert and map.
85
86 · Imager::Engines - Programmable transformations through
87 "transform()", "transform2()" and "matrix_transform()".
88
89 · Imager::Filters - Filters, sharpen, blur, noise, convolve etc. and
90 filter plug-ins.
91
92 · Imager::Expr - Expressions for evaluation engine used by
93 transform2().
94
95 · Imager::Matrix2d - Helper class for affine transformations.
96
97 · Imager::Fountain - Helper for making gradient profiles.
98
99 · Imager::IO - Imager I/O abstraction.
100
101 · Imager::API - using Imager's C API
102
103 · Imager::APIRef - API function reference
104
105 · Imager::Inline - using Imager's C API from Inline::C
106
107 · Imager::ExtUtils - tools to get access to Imager's C API.
108
109 · Imager::Security - brief security notes.
110
111 · Imager::Threads - brief information on working with threads.
112
113 Basic Overview
114 An Image object is created with "$img = Imager->new()". Examples:
115
116 $img=Imager->new(); # create empty image
117 $img->read(file=>'lena.png',type=>'png') or # read image from file
118 die $img->errstr(); # give an explanation
119 # if something failed
120
121 or if you want to create an empty image:
122
123 $img=Imager->new(xsize=>400,ysize=>300,channels=>4);
124
125 This example creates a completely black image of width 400 and height
126 300 and 4 channels.
127
129 In general a method will return false when it fails, if it does use the
130 "errstr()" method to find out why:
131
132 errstr()
133 Returns the last error message in that context.
134
135 If the last error you received was from calling an object method,
136 such as read, call errstr() as an object method to find out why:
137
138 my $image = Imager->new;
139 $image->read(file => 'somefile.gif')
140 or die $image->errstr;
141
142 If it was a class method then call errstr() as a class method:
143
144 my @imgs = Imager->read_multi(file => 'somefile.gif')
145 or die Imager->errstr;
146
147 Note that in some cases object methods are implemented in terms of
148 class methods so a failing object method may set both.
149
150 The "Imager->new" method is described in detail in Imager::ImageTypes.
151
153 Where to find information on methods for Imager class objects.
154
155 addcolors() - "addcolors()" in Imager::ImageTypes - add colors to a
156 paletted image
157
158 addtag() - "addtag()" in Imager::ImageTypes - add image tags
159
160 add_type_extensions() - "add_type_extensions($type, $ext, ...)" in
161 Imager::Files - add extensions for new image file types.
162
163 align_string() - "align_string()" in Imager::Draw - draw text aligned
164 on a point
165
166 alphachannel() - "alphachannel()" in Imager::ImageTypes - return the
167 channel index of the alpha channel (if any).
168
169 arc() - "arc()" in Imager::Draw - draw a filled arc
170
171 bits() - "bits()" in Imager::ImageTypes - number of bits per sample for
172 the image
173
174 box() - "box()" in Imager::Draw - draw a filled or outline box.
175
176 check_file_limits() - "check_file_limits()" in Imager::Files
177
178 circle() - "circle()" in Imager::Draw - draw a filled circle
179
180 close_log() - "close_log()" in Imager::ImageTypes - close the Imager
181 debugging log.
182
183 colorchannels() - "colorchannels()" in Imager::ImageTypes - the number
184 of channels used for color.
185
186 colorcount() - "colorcount()" in Imager::ImageTypes - the number of
187 colors in an image's palette (paletted images only)
188
189 colormodel() - "colorcount()" in Imager::ImageTypes - how color is
190 represented.
191
192 combine() - "combine()" in Imager::Transformations - combine channels
193 from one or more images.
194
195 combines() - "combines()" in Imager::Draw - return a list of the
196 different combine type keywords
197
198 compose() - "compose()" in Imager::Transformations - compose one image
199 over another.
200
201 convert() - "convert()" in Imager::Transformations - transform the
202 color space
203
204 copy() - "copy()" in Imager::Transformations - make a duplicate of an
205 image
206
207 crop() - "crop()" in Imager::Transformations - extract part of an image
208
209 def_guess_type() - "def_guess_type()" in Imager::Files - default
210 function used to guess the output file format based on the output file
211 name
212
213 deltag() - "deltag()" in Imager::ImageTypes - delete image tags
214
215 difference() - "difference()" in Imager::Filters - produce a difference
216 images from two input images.
217
218 errstr() - "errstr()" - the error from the last failed operation.
219
220 filter() - "filter()" in Imager::Filters - image filtering
221
222 findcolor() - "findcolor()" in Imager::ImageTypes - search the image
223 palette, if it has one
224
225 flip() - "flip()" in Imager::Transformations - flip an image,
226 vertically, horizontally
227
228 flood_fill() - "flood_fill()" in Imager::Draw - fill an enclosed or
229 same color area
230
231 getchannels() - "getchannels()" in Imager::ImageTypes - the number of
232 samples per pixel for an image
233
234 getcolorcount() - "getcolorcount()" in Imager::ImageTypes - the number
235 of different colors used by an image (works for direct color images)
236
237 getcolors() - "getcolors()" in Imager::ImageTypes - get colors from the
238 image palette, if it has one
239
240 getcolorusage() - "getcolorusage()" in Imager::ImageTypes
241
242 getcolorusagehash() - "getcolorusagehash()" in Imager::ImageTypes
243
244 get_file_limits() - "get_file_limits()" in Imager::Files
245
246 getheight() - "getheight()" in Imager::ImageTypes - height of the image
247 in pixels
248
249 getmask() - "getmask()" in Imager::ImageTypes - write mask for the
250 image
251
252 getpixel() - "getpixel()" in Imager::Draw - retrieve one or more pixel
253 colors
254
255 getsamples() - "getsamples()" in Imager::Draw - retrieve samples from a
256 row or partial row of pixels.
257
258 getscanline() - "getscanline()" in Imager::Draw - retrieve colors for a
259 row or partial row of pixels.
260
261 getwidth() - "getwidth()" in Imager::ImageTypes - width of the image in
262 pixels.
263
264 img_set() - "img_set()" in Imager::ImageTypes - re-use an Imager object
265 for a new image.
266
267 init() - "init()" in Imager::ImageTypes
268
269 is_bilevel() - "is_bilevel()" in Imager::ImageTypes - returns whether
270 image write functions should write the image in their bilevel (blank
271 and white, no gray levels) format
272
273 is_logging() "is_logging()" in Imager::ImageTypes - test if the debug
274 log is active.
275
276 line() - "line()" in Imager::Draw - draw an interval
277
278 load_plugin() - "load_plugin()" in Imager::Filters
279
280 log() - "log()" in Imager::ImageTypes - send a message to the debugging
281 log.
282
283 make_palette() - "make_palette()" in Imager::ImageTypes - produce a
284 color palette from one or more input images.
285
286 map() - "map()" in Imager::Transformations - remap color channel values
287
288 masked() - "masked()" in Imager::ImageTypes - make a masked image
289
290 matrix_transform() - "matrix_transform()" in Imager::Engines
291
292 maxcolors() - "maxcolors()" in Imager::ImageTypes
293
294 NC() - "NC()" in Imager::Handy
295
296 NCF() - "NCF()" in Imager::Handy
297
298 new() - "new()" in Imager::ImageTypes
299
300 newcolor() - "newcolor()" in Imager::Handy
301
302 newcolour() - "newcolour()" in Imager::Handy
303
304 newfont() - "newfont()" in Imager::Handy
305
306 NF() - "NF()" in Imager::Handy
307
308 open() - "read()" in Imager::Files - an alias for read()
309
310 open_log() - "open_log()" in Imager::ImageTypes - open the debug log.
311
312 parseiptc() - "parseiptc()" in Imager::Files - parse IPTC data from a
313 JPEG image
314
315 paste() - "paste()" in Imager::Transformations - draw an image onto an
316 image
317
318 polygon() - "polygon()" in Imager::Draw
319
320 polyline() - "polyline()" in Imager::Draw
321
322 polypolygon() - "polypolygon()" in Imager::Draw
323
324 preload() - "preload()" in Imager::Files
325
326 read() - "read()" in Imager::Files - read a single image from an image
327 file
328
329 read_multi() - "read_multi()" in Imager::Files - read multiple images
330 from an image file
331
332 read_types() - "read_types()" in Imager::Files - list image types
333 Imager can read.
334
335 register_filter() - "register_filter()" in Imager::Filters
336
337 register_reader() - "register_reader()" in Imager::Files
338
339 register_writer() - "register_writer()" in Imager::Files
340
341 rotate() - "rotate()" in Imager::Transformations
342
343 rubthrough() - "rubthrough()" in Imager::Transformations - draw an
344 image onto an image and use the alpha channel
345
346 scale() - "scale()" in Imager::Transformations
347
348 scale_calculate() - "scale_calculate()" in Imager::Transformations
349
350 scaleX() - "scaleX()" in Imager::Transformations
351
352 scaleY() - "scaleY()" in Imager::Transformations
353
354 setcolors() - "setcolors()" in Imager::ImageTypes - set palette colors
355 in a paletted image
356
357 set_file_limits() - "set_file_limits()" in Imager::Files
358
359 setmask() - "setmask()" in Imager::ImageTypes
360
361 setpixel() - "setpixel()" in Imager::Draw
362
363 setsamples() - "setsamples()" in Imager::Draw
364
365 setscanline() - "setscanline()" in Imager::Draw
366
367 settag() - "settag()" in Imager::ImageTypes
368
369 string() - "string()" in Imager::Draw - draw text on an image
370
371 tags() - "tags()" in Imager::ImageTypes - fetch image tags
372
373 to_paletted() - "to_paletted()" in Imager::ImageTypes
374
375 to_rgb16() - "to_rgb16()" in Imager::ImageTypes
376
377 to_rgb8() - "to_rgb8()" in Imager::ImageTypes
378
379 to_rgb_double() - "to_rgb_double()" in Imager::ImageTypes - convert to
380 double per sample image.
381
382 transform() - "transform()" in Imager::Engines
383
384 transform2() - "transform2()" in Imager::Engines
385
386 type() - "type()" in Imager::ImageTypes - type of image (direct vs
387 paletted)
388
389 unload_plugin() - "unload_plugin()" in Imager::Filters
390
391 virtual() - "virtual()" in Imager::ImageTypes - whether the image has
392 it's own data
393
394 write() - "write()" in Imager::Files - write an image to a file
395
396 write_multi() - "write_multi()" in Imager::Files - write multiple image
397 to an image file.
398
399 write_types() - "read_types()" in Imager::Files - list image types
400 Imager can write.
401
403 animated GIF - "Writing an animated GIF" in Imager::Files
404
405 aspect ratio - "i_xres", "i_yres", "i_aspect_only" in "Common Tags" in
406 Imager::ImageTypes.
407
408 blend - alpha blending one image onto another "rubthrough()" in
409 Imager::Transformations
410
411 blur - "gaussian" in Imager::Filters, "conv" in Imager::Filters
412
413 boxes, drawing - "box()" in Imager::Draw
414
415 changes between image - "Image Difference" in Imager::Filters
416
417 channels, combine into one image - "combine()" in
418 Imager::Transformations
419
420 color - Imager::Color
421
422 color names - Imager::Color, Imager::Color::Table
423
424 combine modes - "Combine Types" in Imager::Draw
425
426 compare images - "Image Difference" in Imager::Filters
427
428 contrast - "contrast" in Imager::Filters, "autolevels" in
429 Imager::Filters
430
431 convolution - "conv" in Imager::Filters
432
433 cropping - "crop()" in Imager::Transformations
434
435 CUR files - "ICO (Microsoft Windows Icon) and CUR (Microsoft Windows
436 Cursor)" in Imager::Files
437
438 "diff" images - "Image Difference" in Imager::Filters
439
440 dpi - "i_xres", "i_yres" in "Common Tags" in Imager::ImageTypes, "Image
441 spatial resolution" in Imager::Cookbook
442
443 drawing boxes - "box()" in Imager::Draw
444
445 drawing lines - "line()" in Imager::Draw
446
447 drawing text - "string()" in Imager::Draw, "align_string()" in
448 Imager::Draw
449
450 error message - "ERROR HANDLING"
451
452 files, font - Imager::Font
453
454 files, image - Imager::Files
455
456 filling, types of fill - Imager::Fill
457
458 filling, boxes - "box()" in Imager::Draw
459
460 filling, flood fill - "flood_fill()" in Imager::Draw
461
462 flood fill - "flood_fill()" in Imager::Draw
463
464 fonts - Imager::Font
465
466 fonts, drawing with - "string()" in Imager::Draw, "align_string()" in
467 Imager::Draw, Imager::Font::Wrap
468
469 fonts, metrics - "bounding_box()" in Imager::Font, Imager::Font::BBox
470
471 fonts, multiple master - "MULTIPLE MASTER FONTS" in Imager::Font
472
473 fountain fill - "Fountain fills" in Imager::Fill, "fountain" in
474 Imager::Filters, Imager::Fountain, "gradgen" in Imager::Filters
475
476 GIF files - "GIF" in Imager::Files
477
478 GIF files, animated - "Writing an animated GIF" in Imager::Files
479
480 gradient fill - "Fountain fills" in Imager::Fill, "fountain" in
481 Imager::Filters, Imager::Fountain, "gradgen" in Imager::Filters
482
483 gray scale, convert image to - "convert()" in Imager::Transformations
484
485 gaussian blur - "gaussian" in Imager::Filters
486
487 hatch fills - "Hatched fills" in Imager::Fill
488
489 ICO files - "ICO (Microsoft Windows Icon) and CUR (Microsoft Windows
490 Cursor)" in Imager::Files
491
492 invert image - "hardinvert" in Imager::Filters, "hardinvertall" in
493 Imager::Filters
494
495 JPEG - "JPEG" in Imager::Files
496
497 limiting image sizes - "Limiting the sizes of images you read" in
498 Imager::Files
499
500 lines, drawing - "line()" in Imager::Draw
501
502 matrix - Imager::Matrix2d, "Matrix Transformations" in Imager::Engines,
503 "transform()" in Imager::Font
504
505 metadata, image - "Tags" in Imager::ImageTypes, Image::ExifTool
506
507 mosaic - "mosaic" in Imager::Filters
508
509 noise, filter - "noise" in Imager::Filters
510
511 noise, rendered - "turbnoise" in Imager::Filters, "radnoise" in
512 Imager::Filters
513
514 paste - "paste()" in Imager::Transformations, "rubthrough()" in
515 Imager::Transformations
516
517 pseudo-color image - "to_paletted()" in Imager::ImageTypes, "new()" in
518 Imager::ImageTypes
519
520 posterize - "postlevels" in Imager::Filters
521
522 PNG files - Imager::Files, "PNG" in Imager::Files
523
524 PNM - "PNM (Portable aNy Map)" in Imager::Files
525
526 rectangles, drawing - "box()" in Imager::Draw
527
528 resizing an image - "scale()" in Imager::Transformations, "crop()" in
529 Imager::Transformations
530
531 RGB (SGI) files - "SGI (RGB, BW)" in Imager::Files
532
533 saving an image - Imager::Files
534
535 scaling - "scale()" in Imager::Transformations
536
537 security - Imager::Security
538
539 SGI files - "SGI (RGB, BW)" in Imager::Files
540
541 sharpen - "unsharpmask" in Imager::Filters, "conv" in Imager::Filters
542
543 size, image - "getwidth()" in Imager::ImageTypes, "getheight()" in
544 Imager::ImageTypes
545
546 size, text - "bounding_box()" in Imager::Font
547
548 tags, image metadata - "Tags" in Imager::ImageTypes
549
550 text, drawing - "string()" in Imager::Draw, "align_string()" in
551 Imager::Draw, Imager::Font::Wrap
552
553 text, wrapping text in an area - Imager::Font::Wrap
554
555 text, measuring - "bounding_box()" in Imager::Font, Imager::Font::BBox
556
557 threads - Imager::Threads
558
559 tiles, color - "mosaic" in Imager::Filters
560
561 transparent images - Imager::ImageTypes, "Transparent PNG" in
562 Imager::Cookbook
563
564 unsharp mask - "unsharpmask" in Imager::Filters
565
566 watermark - "watermark" in Imager::Filters
567
568 writing an image to a file - Imager::Files
569
571 The best place to get help with Imager is the mailing list.
572
573 To subscribe send a message with "subscribe" in the body to:
574
575 imager-devel+request@molar.is
576
577 or use the form at:
578
579 <http://www.molar.is/en/lists/imager-devel/>
580
581 where you can also find the mailing list archive.
582
583 You can report bugs by pointing your browser at:
584
585 <https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Imager>
586
587 or by sending an email to:
588
589 bug-Imager@rt.cpan.org
590
591 Please remember to include the versions of Imager, perl, supporting
592 libraries, and any relevant code. If you have specific images that
593 cause the problems, please include those too.
594
595 If you don't want to publish your email address on a mailing list you
596 can use CPAN::Forum:
597
598 http://www.cpanforum.com/dist/Imager
599
600 You will need to register to post.
601
603 Feedback
604 I like feedback.
605
606 If you like or dislike Imager, you can add a public review of Imager at
607 CPAN Ratings:
608
609 http://cpanratings.perl.org/dist/Imager
610
611 This requires a Bitcard account (http://www.bitcard.org).
612
613 You can also send email to the maintainer below.
614
615 If you send me a bug report via email, it will be copied to Request
616 Tracker.
617
618 Patches
619 I accept patches, preferably against the master branch in git. Please
620 include an explanation of the reason for why the patch is needed or
621 useful.
622
623 Your patch should include regression tests where possible, otherwise it
624 will be delayed until I get a chance to write them.
625
626 To browse Imager's git repository:
627
628 http://git.imager.perl.org/imager.git
629
630 To clone:
631
632 git clone git://git.imager.perl.org/imager.git
633
634 My preference is that patches are provided in the format produced by
635 "git format-patch", for example, if you made your changes in a branch
636 from master you might do:
637
638 git format-patch -k --stdout master >my-patch.txt
639
640 and then attach that to your bug report, either by adding it as an
641 attachment in your email client, or by using the Request Tracker
642 attachment mechanism.
643
645 Tony Cook <tonyc@cpan.org> is the current maintainer for Imager.
646
647 Arnar M. Hrafnkelsson is the original author of Imager.
648
649 Many others have contributed to Imager, please see the "README" for a
650 complete list.
651
653 Imager is licensed under the same terms as perl itself.
654
655 A test font, generated by the Debian packaged Fontforge,
656 FT2/fontfiles/MMOne.pfb, contains a Postscript operator definition
657 copyrighted by Adobe. See adobe.txt in the source for license
658 information.
659
661 perl(1), Imager::ImageTypes(3), Imager::Files(3), Imager::Draw(3),
662 Imager::Color(3), Imager::Fill(3), Imager::Font(3),
663 Imager::Transformations(3), Imager::Engines(3), Imager::Filters(3),
664 Imager::Expr(3), Imager::Matrix2d(3), Imager::Fountain(3)
665
666 <http://imager.perl.org/>
667
668 Affix::Infix2Postfix(3), Parse::RecDescent(3)
669
670 Other perl imaging modules include:
671
672 GD(3), Image::Magick(3), Graphics::Magick
673 <http://www.graphicsmagick.org/perl.html>(3), Prima::Image, IPA.
674
675 For manipulating image metadata see Image::ExifTool.
676
677 If you're trying to use Imager for array processing, you should
678 probably using PDL.
679
680
681
682perl v5.28.1 2019-01-11 Imager(3)